init readme

.gitignore

@@ -1 +1,3 @@
-test-dir*
+test-dir*
+*.json
+coverage*

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.

add-synced-lyrics.sh

@@ -1,118 +1,10 @@
 #!/usr/bin/env bash
 
+# many functions are invoked via variables
+# shellcheck disable=SC2329
+
 set -u
 
-have_cmd() {
-    for cmd in "$@"; do
-        command -v "${cmd}" &>/dev/null || return 1
-    done
-}
-
-# shellcheck disable=SC2329
-void() {
-    echo "$@" &>/dev/null
-}
-
-# shellcheck disable=SC2329
-dry() {
-    local args=("$@")
-    local numArgs="${#args[@]}"
-    test "${numArgs}" -eq 0 && return 0
-    echo "'${args[0]}'"
-    local earlyStop=$((numArgs - 1))
-    for ((i = 1; i < earlyStop; i++)); do
-        echo "  '${args[${i}]}' \\"
-    done
-    echo "  '${args[${i}]}'"
-}
-
-check_required_utils() {
-    local utils=(
-        ffmpeg
-        jq
-        syncedlyrics
-        librelyrics
-        spotify # uv tool install --python 3.8 spotify-cli
-    )
-    local missing=false
-    for util in "${utils[@]}"; do
-        if ! have_cmd "${util}"; then
-            echo "missing ${util}!"
-            missing=true
-        fi
-    done
-
-    if [[ ${missing} == true ]]; then
-        return 1
-    else
-        return 0
-    fi
-}
-
-# shellcheck disable=SC2329
-get_spotify_url() {
-    local search="$1"
-    local response artistAlbumTitle url
-    response="$(
-        spotify \
-            search \
-            --track "${search}" \
-            --limit 1 \
-            --raw
-    )"
-
-    artistAlbumTitle="$(
-        jq -r '.items[0] | "\(.artists[0].name) - \(.album.name) - \(.name)"' \
-            <<<"${response}"
-    )"
-
-    if [[ "${artistAlbumTitle}" != "${search}" ]]; then
-        echo "${search} could not be found"
-        return 1
-    fi
-
-    url="$(
-        jq -r '.items[0] | "\(.external_urls.spotify)"' <<<"${response}"
-    )"
-
-    if [[ -z "${url}" ]]; then
-        echo "could not determine url for ${search}"
-        return 1
-    fi
-
-    echo "${url}"
-}
-
-output_eval_functions() {
-    while read -r line; do
-        IFS=' ' read -r _ _ function <<<"${line}"
-        [[ "${function}" == '_determine_inputs_'* ||
-            "${function}" == set_default_options ]] || continue
-        ${line}
-    done <<<"$(declare -F)"
-}
-
-get_artist_album_title() {
-    local file="$1"
-    local jqFilter='.streams[] | select(.codec_type == "audio") | .tags | "\(.ARTIST) - \(.ALBUM) - \(.TITLE)"'
-    ffprobe \
-        -v error \
-        -show_entries stream \
-        -of json \
-        "${file}" | jq \
-        -r "${jqFilter}"
-}
-
-set_lyric_file_name() {
-    local file="$1"
-    if [[ ! "${file}" =~ ${MUSIC_EXTENSION_REGEX} ]]; then
-        echo "${file} is not a music file"
-        return 1
-    fi
-
-    echo "${file%.opus}.lrc"
-}
-
 bash_basename() {
     local tmp
     path="$1"
@@ -125,245 +17,112 @@ bash_basename() {
     printf '%s\n' "${tmp:-/}"
 }
 
-readonly PROGNAME="$(bash_basename "$0")"
+bash_dirname() {
+    # Usage: dirname "path"
+    local tmp=${1:-.}
 
-usage() {
-    echo "${PROGNAME} [options]
+    [[ $tmp != *[!/]* ]] && {
+        printf '/\n'
+        return
+    }
 
-OPTIONS:
-  -d, --dir       process files in directory
-  -r, --recurse   recursively process directory
-  -f, --file      process one file
-  -n, --dry-run   do not actually add synced lyrics,
-                  just show the files that would be processed
-  -e, --eval      output bash functions that can be directly processed
-                  by eval for use with testing this script.
-  -i, --ignore    ignore errors, and continue attempting to find lyrics
-                  even in the case of errors
-  -h, --help      show this output"
-    exit ${EXIT_CODE:-1}
+    tmp=${tmp%%"${tmp##*[!/]}"}
+
+    [[ $tmp != */* ]] && {
+        printf '.\n'
+        return
+    }
+
+    tmp=${tmp%/*}
+    tmp=${tmp%%"${tmp##*[!/]}"}
+
+    printf '%s\n' "${tmp:-/}"
 }
 
-set_default_options() {
-    DIR=${DIR:-}
-    FILE=${FILE:-}
-    RECURSE=${RECURSE:-false}
-    DRY_RUN=${DRY_RUN:-false}
-    IGNORE=${IGNORE:-false}
-    readonly MUSIC_EXTENSION_REGEX='.*\.(opus)$'
-}
+PROGPATH="$(readlink -f "$0")" || exit 1
+PROGDIR="$(bash_dirname "${PROGPATH}")" || exit 1
+PROGNAME="$(bash_basename "${PROGPATH}")" || exit 1
+# shellcheck disable=SC2034
+readonly PROGPATH PROGDIR PROGNAME || exit 1
 
-process_options() {
-    while [[ $# -gt 0 ]]; do
-        option="$1"
-        value="${2:-}"
-        case "${option}" in
-        -d | --dir)
-            if [[ ! -d "${value}" ]]; then
-                echo "directory ${value} does not exist"
-                usage
-            fi
-            readonly DIR="${value}"
-            shift 2
-            ;;
-        -r | --recurse)
-            readonly RECURSE=true
-            shift 1
-            ;;
-        -n | --dry-run)
-            readonly DRY_RUN=true
-            shift 1
-            ;;
-        -i | --ignore)
-            readonly IGNORE=true
-            shift 1
-            ;;
-        -e | --eval)
-            output_eval_functions
-            exit 0
-            ;;
-        -f | --file)
-            if [[ ! -f "${value}" ]]; then
-                echo "file ${value} does not exist"
-                usage
-            fi
-            readonly FILE="${value}"
-            shift 2
-            ;;
-        -h | --help)
-            EXIT_CODE=0 usage
-            ;;
-        *)
-            echo "bad option"
-            usage
-            ;;
-        esac
-    done
-
-    if [[ "${DIR:-}${FILE:-}" == '' ]]; then
-        echo "either --dir or --file must be used"
-        usage
-    fi
-
-    if [[ -n "${DIR}" && -n "${FILE}" ]]; then
-        echo "cannot process both directory and file"
-        usage
-    fi
-
-    if [[ "${RECURSE}" == true && -n "${FILE}" ]]; then
-        echo "--recurse can only be used with --dir"
-        usage
-    fi
-}
-
-_determine_inputs_fd() {
-    local fdCmd=(
-        fd
-        --type f
-        "${MUSIC_EXTENSION_REGEX}"
-        "${DIR}"
-    )
-
-    if [[ "${RECURSE}" == false ]]; then
-        fdCmd+=(--max-depth 1)
-    fi
-
-    mapfile -t INPUTS < <("${fdCmd[@]}" | sort)
-}
-
-_determine_inputs_find() {
-    local findCmd=(
-        find
-        "${DIR}"
-    )
-
-    if [[ "${RECURSE}" == false ]]; then
-        findCmd+=(-maxdepth 1)
-    fi
-
-    findCmd+=(
-        -regextype posix-extended
-        -regex "${MUSIC_EXTENSION_REGEX}"
-        -type f
-    )
-
-    mapfile -t INPUTS < <("${findCmd[@]}" | sort)
-}
-
-_determine_inputs_bash() {
-    local unsortedInputs=()
-    if [[ "${RECURSE}" == true ]]; then
-        local preGlobstar="$(shopt -p globstar)"
-        shopt -s globstar
-        for f in "${DIR}"/**/*; do
-            unsortedInputs+=("${f}")
-        done
-        ${preGlobstar}
-    else
-        for f in "${DIR}"/**; do
-            unsortedInputs+=("${f}")
-        done
-    fi
-
-    local filteredInputs=()
-    for input in "${unsortedInputs[@]}"; do
-        [[ "${input}" =~ ${MUSIC_EXTENSION_REGEX} ]] || continue
-        filteredInputs+=("${input}")
-    done
-
-    mapfile -t INPUTS < <(printf '%s\n' "${filteredInputs[@]}" | sort)
-}
-
-determine_inputs() {
-    INPUTS=()
-    if [[ -n "${FILE}" ]]; then
-        INPUTS=("${FILE}")
-    elif have_cmd fd; then
-        _determine_inputs_fd || return 1
-    elif have_cmd find; then
-        _determine_inputs_find || return 1
-    else
-        _determine_inputs_bash || return 1
-    fi
-
-    if [[ "${#INPUTS[@]}" -eq 0 ]]; then
-        echo "no inputs found, something is wrong"
-        exit 1
-    fi
-
-    readonly INPUTS
-}
-
-create_tmp_dir() {
-    TMPDIR="$(mktemp -d)" || return 1
-    readonly TMPDIR
-    trap 'rm -rf ${TMPDIR}' EXIT
-}
+for lib in "${PROGDIR}/lib/"*; do
+    # shellcheck disable=SC1090
+    source "${lib}" || exit 1
+done
 
 process_inputs() {
-    local dry='' void=''
-    if [[ "${DRY_RUN}" == true ]]; then
-        dry=dry
-        void=void
-    fi
+    local isrc output ret=0
+    local downloadFuncs=(
+        download_with_lrclib
+        download_with_spotify
+        download_with_deezer
+        download_with_lyricsify
+    )
 
-    local search='' output='' spotifyUrl='' ret=''
-    for input in "${INPUTS[@]}"; do
+    local numInputs="${#INPUTS[@]}"
+    for ((i = 0; i < numInputs; i++)); do
         if [[ ${IGNORE} == false && ${ret} -ne 0 ]]; then
             return 1
         fi
 
-        if [[ "${input,,}" == *'instrumental'* ]]; then
-            echo "${input} is instrumental, skipping"
+        local input="${INPUTS[${i}]}"
+        echo_info "processing $((i + 1))/${numInputs}: ${input}"
+
+        if [[ "${input,,}" == *'instrumental'* ||
+            "${input,,}" == *'acoustic'* ]]; then
+            echo_pass "${input} is instrumental, skipping"
             continue
         fi
 
-        output="$(set_lyric_file_name "${input}")"
-        if [[ ! -f "${output}" ]]; then
-            echo "processing ${input}"
-            search="$(get_artist_album_title "${input}")"
+        output=''
+        if ! output="$(set_lyric_file_name "${input}")"; then
+            echo_fail "could not determine lyric file name for ${input}"
+            ret=1
+            continue
+        fi
 
-            # try with syncedlyrics first
-            ${dry} syncedlyrics \
-                --synced-only \
-                --output "${output}" \
-                "${search}"
+        if validate_song_lyrics "${input}" "${output}"; then
+            echo_pass "${input} already has lyrics, skipping"
+            continue
+        fi
 
-            if ! ${void} test -f "${output}"; then
-                for f in "${TMPDIR}"/*; do
-                    if [[ -f "${f}" ]]; then
-                        echo "tempdir ${TMPDIR} is not empty!"
-                        echo "aborting operation"
-                        return 1
-                    fi
-                done
+        isrc=''
+        if ! isrc="$(get_file_isrc "${input}")"; then
+            ret=1
+            continue
+        fi
 
-                # try with librelyrics-spotify next
-                if ! spotifyUrl="$(${dry} get_spotify_url "${search}")"; then
-                    ret=1
-                    continue
-                fi
-
-                if ! ${dry} librelyrics \
-                    --directory "${TMPDIR}" \
-                    "${spotifyUrl}"; then
-                    ret=1
-                    continue
-                fi
-
-                if ! ${dry} mv "${TMPDIR}"/*.lrc "${output}"; then
-                    ret=1
-                    continue
-                fi
-            fi
-
-            if ! ${void} test -f "${output}"; then
-                echo "failed to get lyrics for ${input}"
-                ret=1
+        local tmpOutput="${TMPDIR}/$(bash_basename "${output}")"
+        for func in "${downloadFuncs[@]}"; do
+            # try to download
+            if ! "${func}" "${isrc}" "${tmpOutput}"; then
                 continue
             fi
+
+            # validate
+            if validate_lrc "${tmpOutput}"; then
+                # passed download and validation, stop processing
+                break
+            fi
+        done
+
+        # skip processing since no files should be modified
+        [[ ${DRY_RUN} == true ]] && continue
+
+        if [[ -f "${tmpOutput}" ]]; then
+            add_lyrics_to_song \
+                "${input}" \
+                "${tmpOutput}" \
+                "${output}" &&
+                echo_pass "added lyrics for ${input}"
+        else
+            echo_fail "could not find lyrics for ${input}"
+            ret=1
         fi
+
     done
+
+    return ${ret}
 }
 
 check_required_utils || exit 1

lib/0-utils.sh

@@ -0,0 +1,423 @@
+#!/usr/bin/env bash
+
+# many functions are invoked via variables
+# shellcheck disable=SC2329
+
+# check commands exist
+# "$@" commands to check
+have_cmd() {
+    for cmd in "$@"; do
+        command -v "${cmd}" &>/dev/null || return 1
+    done
+}
+
+# validate results from `jq -r`
+jq_result_valid() {
+    local result="$1"
+    if [[ -z "${result}" || "${result}" == 'null' ]]; then
+        return 1
+    fi
+    return 0
+}
+
+# ANSI colors
+readonly RED='\e[0;31m'
+readonly GREEN='\e[0;32m'
+readonly PURPLE='\e[0;35m'
+readonly YELLOW='\e[0;33m'
+readonly CYAN='\e[0;36m'
+readonly NC='\e[0m'
+
+stderr() {
+    local word="${WORD:-}"
+    local color="${COLOR:-}"
+    local function="${FUNCNAME[2]}"
+    if [[ "${function}" =~ debug|void ]]; then
+        function="${FUNCNAME[3]}"
+    fi
+    echo \
+        -e \
+        "${color}${word}${NC}" \
+        "[${function}]" \
+        "$@" 1>&2
+}
+echo_info() { WORD=INFO COLOR="${CYAN}" stderr "$@"; }
+echo_fail() { WORD=FAIL COLOR="${RED}" stderr "$@"; }
+echo_pass() { WORD=PASS COLOR="${GREEN}" stderr "$@"; }
+echo_debug() { WORD=DBUG COLOR="${PURPLE}" stderr "$@"; }
+
+# only perform the command given if ${DEBUG} is enabled
+debug() {
+    if [[ ${DEBUG} == false ]]; then
+        return 0
+    fi
+
+    "$@"
+}
+
+# only perform the command given if ${DRY_RUN} is disabled
+void() {
+    if [[ ${DRY_RUN} == true ]]; then
+        return 0
+    fi
+
+    "$@"
+}
+
+# print out "$@" formatted for bash
+# if ${DRY_RUN} is enabled
+# otherwise, execute the actual command
+dry() {
+    local cmd=("$@")
+    if [[ ${DRY_RUN} == true ]]; then
+        local numCmd="${#cmd[@]}"
+        test "${numCmd}" -eq 0 && return 0
+        local firstLine="'${cmd[0]}'"
+        test "${numCmd}" -gt 1 && firstLine+=' \'
+        stderr "${firstLine}"
+        local earlyStop=$((numCmd - 1))
+        for ((i = 1; i < earlyStop; i++)); do
+            stderr "  '${cmd[${i}]}' \\"
+        done
+        stderr "  '${cmd[${i}]}'"
+    else
+        "${cmd[@]}"
+        return $?
+    fi
+}
+
+# check required utilities for this project
+check_required_utils() {
+    local utils=(
+        # coreutils
+        bash
+        cat
+        sort
+        base64
+        mktemp
+        readlink
+
+        jq
+        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
+            echo_fail "missing ${util}!"
+            missing=true
+        fi
+    done
+
+    if [[ ${missing} == true ]]; then
+        return 1
+    else
+        return 0
+    fi
+}
+
+echo_if_fail() {
+    local cmd=("$@")
+    local output
+    output="$("${cmd[@]}" 2>&1)"
+    local ret=$?
+
+    if [[ ${ret} -ne 0 ]]; then
+        echo_fail "${cmd[*]}"
+        echo_fail "${output}"
+    fi
+
+    return ${ret}
+}
+
+cache_command() {
+    local cmd=("$@")
+    local hash cacheFile cmdOut contents ret
+    hash="$(sha256sum <<<"${cmd[*]}")" || return 1
+    read -r cacheFile _ <<<"${hash}"
+    cacheFilePath="${CACHE_DIR}/${cacheFile}"
+    if [[ -f "${cacheFilePath}" ]]; then
+        mapfile -t cmdArr <<<"${cmd[*]}"
+        local skipLines="${#cmdArr[@]}"
+        mapfile -t contents <"${cacheFilePath}"
+        ret=$?
+        # skip N lines respective to the command length
+        printf '%s\n' "${contents[@]:${skipLines}}"
+    else
+        cmdOut="$(dry "${cmd[@]}")"
+        ret=$?
+        if [[ ${ret} -eq 0 && ${DRY_RUN} == false ]]; then
+            {
+                echo "${cmd[*]}"
+                echo "${cmdOut}"
+            } >"${cacheFilePath}" || return 1
+            echo "${cmdOut}"
+        fi
+    fi
+
+    return "${ret}"
+}
+
+create_tmp_dir() {
+    [[ -n "${TMPDIR:-}" ]] && return
+
+    TMPDIR="$(mktemp -d)" || return 1
+    readonly TMPDIR
+    trap 'rm -rf ${TMPDIR}' EXIT
+}
+
+check_tmp_dir_empty() {
+    for f in "${TMPDIR}"/*; do
+        if [[ -f "${f}" ]]; then
+            echo_fail "tempdir ${TMPDIR} is not empty!"
+            echo_fail "contains ${f}"
+            echo_fail "aborting operation"
+            # execution becomes undefined if TMPDIR is not empty
+            exit 1
+        fi
+    done
+
+    return 0
+}
+
+# librelyrics only exposes a directory to download to
+# so this wrapper function downloads to a directory
+# and then outputs the contents of the downloaded file
+# to stdout so it can effectively be cached
+librelyrics_dl() {
+    local url="$1"
+    check_tmp_dir_empty || return 1
+    librelyrics \
+        --directory "${TMPDIR}" \
+        "${url}" 1>&2
+    local librelyricsRet=$?
+
+    local downloadedFile=''
+    for f in "${TMPDIR}/"*; do
+        if [[ -f "${f}" ]]; then
+            downloadedFile="${f}"
+            break
+        fi
+    done
+
+    if [[ ${librelyricsRet} -eq 0 && -z ${downloadedFile} ]]; then
+        echo_fail "failed to download file for ${url} despite no librelyrics error"
+        return 1
+    fi
+
+    local fileContents=''
+    if [[ -n "${downloadedFile}" ]]; then
+        fileContents="$(<"${downloadedFile}")"
+        rm "${downloadedFile}" || return 1
+    fi
+
+    if [[ ${librelyricsRet} -eq 0 && -z ${fileContents} ]]; then
+        echo_fail "failed to read file for ${url} despite no librelyrics error"
+        return 1
+    fi
+
+    echo "${fileContents}"
+}
+
+download_with_librelyrics() {
+    local isrc="$1"
+    local output="$2"
+    local urlType="$3"
+
+    if [[ ! "${urlType}" =~ spotify|deezer ]]; then
+        echo_fail "only spotify|deezer are supported"
+        return 1
+    fi
+
+    local url=''
+    url="$(get_"${urlType}"_url "${isrc}")" || return 1
+
+    local lyrics=''
+    lyrics="$(cache_command \
+        librelyrics_dl \
+        "${url}")"
+
+    if [[ -z "${lyrics}" ]]; then
+        debug echo_fail "could not find lyrics for ${isrc} using ${urlType}"
+        return 1
+    fi
+
+    debug echo_info "found lyrics for ${isrc} with ${urlType}"
+    echo "${lyrics}" >"${output}"
+}
+
+output_eval_functions() {
+    while read -r line; do
+        IFS=' ' read -r _ _ function <<<"${line}"
+        [[ "${function}" == '_determine_inputs_'* ||
+            "${function}" == set_default_options ]] || continue
+        ${line}
+    done <<<"$(declare -F)"
+    check_required_utils --print-required
+}
+
+get_file_isrc() {
+    local file="$1"
+    local probe='' jqResult=''
+
+    local probe=''
+    probe="$(
+        ffprobe \
+            -v error \
+            -show_entries stream \
+            -of json \
+            "${file}"
+    )" || return 1
+
+    local jqFilter='.streams[] | select(.codec_type == "audio") | .tags | with_entries(.key |= ascii_downcase) | .isrc'
+    jqResult="$(jq -r "${jqFilter}" <<<"${probe}")"
+
+    if [[ "${jqResult}" == 'null' ]]; then
+        echo_fail "could not find ISRC for ${file}"
+        return 1
+    fi
+    echo "${jqResult}"
+}
+
+get_file_lyrics() {
+    local file="$1"
+    local probe='' jqResult=''
+
+    local probe=''
+    probe="$(
+        ffprobe \
+            -v error \
+            -show_entries stream \
+            -of json \
+            "${file}"
+    )" || return 1
+
+    local jqFilter='.streams[] | select(.codec_type == "audio") | .tags | with_entries(.key |= ascii_downcase) | .lyrics'
+    jqResult="$(jq -r "${jqFilter}" <<<"${probe}")"
+
+    if [[ "${jqResult}" == 'null' ]]; then
+        debug echo_fail "could not find lyrics for ${file}"
+        return 1
+    fi
+    echo "${jqResult}"
+}
+
+is_music_file() {
+    local file="$1"
+    [[ "${file}" =~ ${MUSIC_EXTENSION_REGEX} ]]
+}
+
+is_lrc_file() {
+    local file="$1"
+    [[ "${file}" == *'.lrc' ]]
+}
+
+set_lyric_file_name() {
+    local file="$1"
+    if ! is_music_file "${file}"; then
+        echo_fail "${file} is not a music file"
+        return 1
+    fi
+
+    echo "${file%.opus}.lrc"
+}
+
+validate_lrc() {
+    local file="$1"
+
+    # file does not exist, invalid
+    if [[ ! -f "${file}" ]]; then
+        return 1
+    fi
+
+    # file is not lyric file, invalid
+    if ! is_lrc_file "${file}"; then
+        return 1
+    fi
+
+    mapfile -t fileContents <"${file}"
+
+    local valid=1
+    for line in "${fileContents[@]}"; do
+        [[ "${#line}" -eq 0 ]] && continue
+        if [[ "${line}" != '['* && "${line}" != '#'* ]]; then
+            valid=1
+            break
+        fi
+        valid=0
+    done
+
+    if [[ ${valid} -eq 1 ]]; then
+        debug echo_fail "${file} is not valid lrc file"
+        dry rm "${file}" || return 1
+    fi
+
+    return ${valid}
+}
+
+validate_song_lyrics() {
+    local songFile="$1"
+    local lyricsDestination="$2"
+
+    # embed or not both get validated
+    validate_lrc "${lyricsDestination}"
+    local validateDestination=$?
+
+    # only continue to validate for embed
+    if [[ ${EMBED} == false ]]; then
+        return ${validateDestination}
+    fi
+
+    local tmpLyricsFile="${TMPDIR}/$(bash_basename "${lyricsDestination}")"
+    get_file_lyrics "${songFile}" >"${tmpLyricsFile}"
+    validate_lrc "${tmpLyricsFile}"
+    local validateRet=$?
+    [[ ${validateRet} -eq 0 ]] && rm "${tmpLyricsFile}"
+
+    return ${validateRet}
+}
+
+add_lyrics_to_song() {
+    local songFile="$1"
+    local lyricsToAdd="$2"
+    local lyricsDestination="$3"
+
+    # this function removes file so be extra certain
+    is_music_file "${songFile}" &&
+        is_lrc_file "${lyricsToAdd}" &&
+        is_lrc_file "${lyricsDestination}" || return 1
+
+    if [[ ${EMBED} == false ]]; then
+        mv "${lyricsToAdd}" "${lyricsDestination}" &>/dev/null
+        return $?
+    fi
+
+    local tmpSongFile="${TMPDIR}/$(bash_basename "${songFile}")"
+    echo_if_fail \
+        ffmpeg \
+        -hide_banner \
+        -i "${songFile}" \
+        -metadata "LYRICS=$(<"${lyricsToAdd}")" \
+        -c copy \
+        "${tmpSongFile}"
+    local ffmpegRet=$?
+    rm "${lyricsToAdd}"
+
+    if [[ ${ffmpegRet} -eq 0 ]]; then
+        mv "${tmpSongFile}" "${songFile}" &>/dev/null || return 1
+        if [[ -f "${lyricsDestination}" ]]; then
+            rm "${lyricsDestination}" || return 1
+        fi
+    fi
+}

lib/deezer.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+
+# many functions are invoked via variables
+# shellcheck disable=SC2329
+
+get_deezer_isrc_response() {
+    local isrc="$1"
+    if [[ -z "${isrc}" ]]; then
+        echo_fail "missing isrc"
+        return 1
+    fi
+
+    cache_command \
+        curl \
+        --silent \
+        --retry 3 \
+        "https://api.deezer.com/track/isrc:${isrc}"
+}
+
+get_deezer_url() {
+    local isrc="$1"
+    if [[ -z "${isrc}" ]]; then
+        echo_fail "missing isrc"
+        return 1
+    fi
+
+    local deezerResponse=''
+    deezerResponse="$(get_deezer_isrc_response "${isrc}")" || return 1
+
+    local jqResult=''
+    jqResult="$(jq -r .link <<<"${deezerResponse}")"
+
+    if ! jq_result_valid "${jqResult}"; then
+        echo_fail "could not find link from deezer for ${isrc}"
+        return 1
+    fi
+
+    echo "${jqResult}"
+}
+
+download_with_deezer() {
+    local isrc="$1"
+    local output="$2"
+    download_with_librelyrics \
+        "${isrc}" \
+        "${output}" \
+        deezer
+}

lib/lrclib.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+# many functions are invoked via variables
+# shellcheck disable=SC2329
+
+get_lrclib_api_response() {
+    local isrc="$1"
+    local deezerResponse=''
+    deezerResponse="$(get_deezer_isrc_response "${isrc}")" || return 1
+
+    # get metadata from deezer
+    local deezerMetadata=(
+        "track .title"
+        "artist .artist.name"
+        "album .album.title"
+        "duration .duration"
+    )
+    for data in "${deezerMetadata[@]}"; do
+        IFS=' ' read -r env jqFilter <<<"${data}"
+        jqResult="$(jq -r "${jqFilter}" <<<"${deezerResponse}")"
+        if ! jq_result_valid "${jqResult}"; then
+            echo_fail "could not determine lrclib ${env} for ${isrc}"
+            return 1
+        fi
+        declare "${env}=${jqResult}"
+        debug echo_debug "${env}=${jqResult}"
+    done
+
+    # variables assigned above
+    # shellcheck disable=SC2154
+    cache_command \
+        curl \
+        "https://lrclib.net/api/get" \
+        --silent \
+        --get \
+        --data-urlencode "track_name=${track}" \
+        --data-urlencode "artist_name=${artist}" \
+        --data-urlencode "album_name=${album}" \
+        --data-urlencode "duration=${duration}"
+}
+
+download_with_lrclib() {
+    local isrc="$1"
+    local output="$2"
+
+    # get lrclib ID
+    local lrclibResponse syncedLyrics
+    lrclibResponse="$(get_lrclib_api_response "${isrc}")"
+    syncedLyrics="$(jq -r .syncedLyrics <<<"${lrclibResponse}")"
+    if ! jq_result_valid "${syncedLyrics}"; then
+        debug echo_fail "could not find lyrics for ${isrc}"
+        return 1
+    fi
+
+    echo "${syncedLyrics}" >"${output}"
+}

lib/lyricsify.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+
+FLARESOLVERR_PORT="${FLARESOLVERR_PORT:-8191}"
+validate_flaresolverr() {
+    local checkMsg="$(curl --connect-timeout 1 -s localhost:${FLARESOLVERR_PORT} | jq -r .msg)"
+
+    if [[ "${checkMsg}" == 'FlareSolverr is ready!' ]]; then
+        return 0
+    fi
+
+    debug echo_debug 'flaresolverr not running, attempting to start with docker'
+    local containerName='flaresolverr'
+    docker inspect ${containerName} &>/dev/null && docker container rm ${containerName}
+
+    echo_if_fail docker run -d \
+        --name=flaresolverr \
+        -p ${FLARESOLVERR_PORT}:${FLARESOLVERR_PORT} \
+        -e LOG_LEVEL=info \
+        --restart unless-stopped \
+        ghcr.io/flaresolverr/flaresolverr:latest
+    local startupRet=$?
+
+    [[ ${startupRet} -ne 0 ]] && return ${startupRet}
+
+    #  wait a little to make sure the container is ready
+    sleep 3
+    return ${startupRet}
+}
+
+get_lyricsify_response() {
+    local isrc="$1"
+
+    validate_flaresolverr || return 1
+
+    local deezerResponse=''
+    deezerResponse="$(get_deezer_isrc_response "${isrc}")" || return 1
+
+    # lyricsify uses artist - song name for URL
+    # so obtain data from deezer
+    local deezerMetadata=(
+        "track .title"
+        "artist .artist.name"
+    )
+    for data in "${deezerMetadata[@]}"; do
+        IFS=' ' read -r env jqFilter <<<"${data}"
+        jqResult="$(jq -r "${jqFilter}" <<<"${deezerResponse}")"
+        if ! jq_result_valid "${jqResult}"; then
+            echo_fail "could not determine lyricsify ${env} for ${isrc}"
+            return 1
+        fi
+        declare "${env}=${jqResult}"
+        debug echo_debug "${env}=${jqResult}"
+    done
+
+    # variables assigned above
+    # shellcheck disable=SC2154
+    artist="${artist,,}"
+    track="${track,,}"
+    artist="${artist// /-}"
+    track="${track// /-}"
+    local lyricsifyUrl="https://www.lyricsify.com/lyrics/${artist}/${track}"
+    debug echo_debug "using ${lyricsifyUrl}"
+
+    local jsonPayload
+    jsonPayload="$(
+        jq -n \
+            --arg cmd 'request.get' \
+            --arg url "${lyricsifyUrl}" \
+            --argjson timeout 60000 \
+            '{cmd: $cmd, url: $url, maxTimeout: $timeout}'
+    )" || return 1
+
+    cache_command \
+        curl \
+        -L \
+        -X POST \
+        "http://localhost:${FLARESOLVERR_PORT}/v1" \
+        -H 'Content-Type: application/json' \
+        --data-raw "${jsonPayload}"
+}
+
+process_lyricsify_response() {
+    local response="$1"
+
+    local responseMessage="$(jq -r '.message' <<<"${response}")"
+    if [[ "${responseMessage}" != 'Challenge solved!' ]]; then
+        debug echo_fail "could not solve challenge"
+        return 1
+    fi
+
+    local solution="$(jq -r '.solution.response' <<<"${response}")"
+
+    local variableSearch='lrcText'
+    while read -r line; do
+        if [[ "${line}" == *"var ${variableSearch} = "* ]]; then
+            node -e "${line} ; console.log(${variableSearch})"
+            return $?
+        fi
+    done <<<"${solution}"
+
+    return 1
+}
+
+DOWNLOAD_FUNCTIONS+=(download_with_lyricsify)
+download_with_lyricsify() {
+    local isrc="$1"
+    local output="$2"
+
+    local lyricsifyResponse syncedLyrics
+    lyricsifyResponse="$(get_lyricsify_response "${isrc}")" || return 1
+    syncedLyrics="$(process_lyricsify_response "${lyricsifyResponse}")" || return 1
+
+    echo "${syncedLyrics}" >"${output}"
+}

lib/options.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+
+# many functions are invoked via variables
+# shellcheck disable=SC2329
+
+usage() {
+    echo "${PROGNAME} [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."
+    exit "${EXIT_CODE:-1}"
+}
+
+set_default_options() {
+    DIR=${DIR:-}
+    FILE=${FILE:-}
+    RECURSE=${RECURSE:-false}
+    DRY_RUN=${DRY_RUN:-false}
+    IGNORE=${IGNORE:-false}
+    EMBED=${EMBED:-false}
+    DEBUG=${DEBUG:-false}
+
+    # cache
+    CACHE_HOME="${XDG_CACHE_HOME:-"${HOME}/.cache"}"
+    CACHE_DIR="${CACHE_HOME}/add-synced-lyrics"
+    if [[ ! -d "${CACHE_DIR}" ]]; then
+        mkdir "${CACHE_DIR}" || return 1
+    fi
+
+    readonly MUSIC_EXTENSION_REGEX='.*\.(opus)$'
+}
+
+process_options() {
+    while [[ $# -gt 0 ]]; do
+        option="$1"
+        value="${2:-}"
+        case "${option}" in
+        -d | --dir)
+            if [[ ! -d "${value}" ]]; then
+                echo "directory ${value} does not exist"
+                usage
+            fi
+            readonly DIR="${value}"
+            shift 2
+            ;;
+        -r | --recurse)
+            readonly RECURSE=true
+            shift 1
+            ;;
+        -n | --dry-run)
+            readonly DRY_RUN=true
+            shift 1
+            ;;
+        -i | --ignore)
+            readonly IGNORE=true
+            shift 1
+            ;;
+        -e | --embed)
+            readonly EMBED=true
+            shift 1
+            ;;
+        -f | --file)
+            if [[ ! -f "${value}" ]]; then
+                echo "file ${value} does not exist"
+                usage
+            fi
+            readonly FILE="${value}"
+            shift 2
+            ;;
+        --debug)
+            readonly DEBUG=true
+            shift 1
+            ;;
+        --eval)
+            output_eval_functions
+            exit 0
+            ;;
+        -h | --help)
+            EXIT_CODE=0 usage
+            ;;
+        *)
+            echo "bad option"
+            usage
+            ;;
+        esac
+    done
+
+    if [[ "${DIR:-}${FILE:-}" == '' ]]; then
+        echo "either --dir or --file must be used"
+        usage
+    fi
+
+    if [[ -n "${DIR}" && -n "${FILE}" ]]; then
+        echo "cannot process both directory and file"
+        usage
+    fi
+
+    if [[ "${RECURSE}" == true && -n "${FILE}" ]]; then
+        echo "--recurse can only be used with --dir"
+        usage
+    fi
+}
+
+_determine_inputs_fd() {
+    local fdCmd=(
+        fd
+        --type f
+        "${MUSIC_EXTENSION_REGEX}"
+        "${DIR}"
+    )
+
+    if [[ "${RECURSE}" == false ]]; then
+        fdCmd+=(--max-depth 1)
+    fi
+
+    mapfile -t INPUTS < <("${fdCmd[@]}" | sort)
+}
+
+_determine_inputs_find() {
+    local findCmd=(
+        find
+        "${DIR}"
+    )
+
+    if [[ "${RECURSE}" == false ]]; then
+        findCmd+=(-maxdepth 1)
+    fi
+
+    findCmd+=(
+        -regextype posix-extended
+        -regex "${MUSIC_EXTENSION_REGEX}"
+        -type f
+    )
+
+    mapfile -t INPUTS < <("${findCmd[@]}" | sort)
+}
+
+_determine_inputs_bash() {
+    local unsortedInputs=()
+    local pattern="${DIR}/*"
+    shopt -s nullglob globstar || return 1
+
+    [[ "${RECURSE}" == true ]] && pattern="${DIR}/**/*"
+    mapfile -t unsortedInputs < <(printf '%s\n' ${pattern})
+
+    local filteredInputs=()
+    for input in "${unsortedInputs[@]}"; do
+        [[ "${input}" =~ ${MUSIC_EXTENSION_REGEX} ]] || continue
+        filteredInputs+=("${input}")
+    done
+
+    mapfile -t INPUTS < <(printf '%s\n' "${filteredInputs[@]}" | sort)
+}
+
+determine_inputs() {
+    INPUTS=()
+    if [[ -n "${FILE}" ]]; then
+        INPUTS=("${FILE}")
+    elif have_cmd fd; then
+        _determine_inputs_fd || return 1
+    elif have_cmd find; then
+        _determine_inputs_find || return 1
+    else
+        _determine_inputs_bash || return 1
+    fi
+
+    if [[ "${#INPUTS[@]}" -eq 0 ]]; then
+        echo "no inputs found, something is wrong"
+        exit 1
+    fi
+
+    readonly INPUTS
+}

lib/spotify.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+
+# many functions are invoked via variables
+# shellcheck disable=SC2329
+
+get_spotify_url() {
+    local isrc="$1"
+    if [[ -z "${isrc}" ]]; then
+        echo_fail "missing isrc"
+        return 1
+    fi
+
+    local search="isrc:${isrc}"
+    local response
+    response="$(
+        cache_command \
+            spotify \
+            search \
+            --track \
+            "${search}" \
+            --limit 1 \
+            --raw
+    )" || return 1
+
+    local tags=(
+        spotifyISRC
+        spotifyURL
+    )
+    # unset tag values
+    for tag in "${tags[@]}"; do
+        declare "${tag}="
+    done
+
+    local jqFilter='.items[] | "\(.external_ids.isrc)|\(.external_urls.spotify)"'
+    local jqOutput="$(jq -r "${jqFilter}" <<<"${response}")"
+
+    # compare tags versus the reference for each line
+    local foundMatching=false
+    while read -r line; do
+        IFS='|' read -r "${tags[@]}" <<<"${line}"
+
+        for tag in "${tags[@]}"; do
+            declare -n spotifyTagValue="${tag}"
+            debug echo_debug "${tag}=${spotifyTagValue}"
+        done
+
+        # shellcheck disable=SC2154
+        if [[ "${spotifyISRC,,}" == "${isrc,,}" ]]; then
+            foundMatching=true
+            break
+        fi
+    done <<<"${jqOutput}"
+
+    if [[ "${foundMatching}" == false ]]; then
+        debug echo_fail "could not find matching spotify track for ${isrc}"
+        return 1
+    fi
+
+    # shellcheck disable=SC2154
+    echo "${spotifyURL}"
+    return 0
+}
+
+download_with_spotify() {
+    local isrc="$1"
+    local output="$2"
+    download_with_librelyrics \
+        "${isrc}" \
+        "${output}" \
+        spotify
+}

test-add-synced-lyrics.sh

@@ -3,31 +3,134 @@
 # "${test}" invokes test_ functions
 # shellcheck disable=SC2329
 
-set -u
+set -eu
 
-readonly THIS_DIR="$(dirname "$(readlink -f "$0")")"
-readonly TEST_DIR="${THIS_DIR}/test-dir"
-readonly TEST_FILE_1="${TEST_DIR}/03 - Back Burner.opus"
-readonly TEST_FILE_2="${TEST_DIR}/subdir/05 - Composure.opus"
-readonly PROG="${THIS_DIR}/add-synced-lyrics.sh"
+bash_basename() {
+    local tmp
+    path="${1:-}"
+    suffix="${2:-''}"
+
+    tmp=${path%"${path##*[!/]}"}
+    tmp=${tmp##*/}
+    tmp=${tmp%"${suffix/"$tmp"/}"}
+
+    printf '%s\n' "${tmp:-/}"
+}
+
+bash_dirname() {
+    # Usage: dirname "path"
+    local tmp=${1:-.}
+
+    [[ $tmp != *[!/]* ]] && {
+        printf '/\n'
+        return
+    }
+
+    tmp=${tmp%%"${tmp##*[!/]}"}
+
+    [[ $tmp != */* ]] && {
+        printf '.\n'
+        return
+    }
+
+    tmp=${tmp%/*}
+    tmp=${tmp%%"${tmp##*[!/]}"}
+
+    printf '%s\n' "${tmp:-/}"
+}
+
+PROGPATH="$(readlink -f "$0")" || exit 1
+PROGDIR="$(bash_dirname "${PROGPATH}")" || exit 1
+PROGNAME="$(bash_basename "${PROGPATH}")" || exit 1
+readonly PROGPATH PROGDIR PROGNAME || exit 1
+
+# to normalize paths
+cd "${PROGDIR}"
+
+readonly TEST_DIR="test-dir"
+# lyrics exist for this song
+readonly GOOD_SONG="${TEST_DIR}/the cold sun.opus"
+readonly GOOD_LYRICS="${GOOD_SONG//.opus/.lrc}"
+readonly GOOD_ISRC='TCJPF1733509'
+# lyrics do not exist for this song
+readonly BAD_SONG="${TEST_DIR}/subdir/avalanche.opus"
+readonly BAD_LYRICS="${BAD_SONG//.opus/.lrc}"
+readonly BAD_ISRC='US5261822978'
+# program to test
+readonly PROG="add-synced-lyrics.sh"
+# coverage
+readonly COVERAGE_DIR="coverage"
+readonly COVERAGE_FILE="${COVERAGE_DIR}/coverage"
+
+run_test_cmd() {
+    local expectedRetval="${1:-}"
+
+    shift 1
+    local cmd=("$@")
+
+    # check for empty args for setup tests to run
+    [[ -z "${expectedRetval}" && -z "${cmd[*]}" ]] && return
+
+    # check a value was given
+    if [[ ! "${expectedRetval}" =~ [0-9] ]]; then
+        echo "expectedRetval not given"
+        exit 1
+    fi
+
+    local output
+    output="$("${cmd[@]}" 2>&1)"
+    local actualRetval=$?
+
+    declare -g CMD_OUTPUT="${output}"
+    declare -g CMD_RETURN="${actualRetval}"
+    if [[ ${expectedRetval} -ne ${actualRetval} ]]; then
+        echo "${expectedRetval} != ${actualRetval} for ${cmd[*]}"
+        return 1
+    else
+        return 0
+    fi
+}
+
+test_help_option() {
+    add-synced-lyrics --help
+}
 
 test_bad_input() {
     # incomplete args
-    "${PROG}" && return 1
-    "${PROG}" --file && return 1
-    "${PROG}" --dir && return 1
-    "${PROG}" --recurse && return 1
+    run_test_cmd \
+        1 \
+        add-synced-lyrics
+    run_test_cmd \
+        1 \
+        add-synced-lyrics --file
+    run_test_cmd \
+        1 \
+        add-synced-lyrics --dir
+    run_test_cmd \
+        1 \
+        add-synced-lyrics --recurse
 
     # incorrect mixmatch
-    "${PROG}" --file "${PROG}" --recurse && return 1
-    "${PROG}" --file "${PROG}" --dir "${THIS_DIR}" && return 1
-    "${PROG}" --file "${PROG}" --dir "${THIS_DIR}" --recurse && return 1
+    run_test_cmd \
+        1 \
+        add-synced-lyrics --file "${PROGPATH}" --recurse
+    run_test_cmd \
+        1 \
+        add-synced-lyrics --file "${PROGPATH}" --dir "${PROGDIR}"
+    run_test_cmd \
+        1 \
+        add-synced-lyrics --file "${PROGPATH}" --dir "${PROGDIR}" --recurse
+
+    # non-existent flag
+    run_test_cmd \
+        1 \
+        add-synced-lyrics --this-flag-does-not-exist
 
     return 0
 }
 
 test_determine_inputs() (
-    eval "$("${PROG}" --eval)"
+    eval "$(add-synced-lyrics --eval)"
     set_default_options
 
     DIR="${TEST_DIR}"
@@ -44,12 +147,12 @@ test_determine_inputs() (
     echo "comparing bash vs fd"
     diff \
         <(printf '%s\n' "${bashInputs[@]}") \
-        <(printf '%s\n' "${fdInputs[@]}") || return 1
+        <(printf '%s\n' "${fdInputs[@]}")
 
     echo "comparing fd vs find"
     diff \
         <(printf '%s\n' "${fdInputs[@]}") \
-        <(printf '%s\n' "${findInputs[@]}") || return 1
+        <(printf '%s\n' "${findInputs[@]}")
 
     return 0
 )
@@ -58,37 +161,137 @@ test_determine_inputs_recurse() {
     RECURSE=true test_determine_inputs
 }
 
-test_file_dry() {
-    "${PROG}" --file "${TEST_FILE_1}" --dry-run || return 1
+test_determine_inputs_bash() {
+    eval "$(add-synced-lyrics --eval)"
+    # TEST_ADD_BIN guaranteed to be single word
+    # shellcheck disable=SC2206
+    local utils=(
+        ${utils}
+        ${TEST_ADD_BIN:-}
+    )
 
-    return 0
+    for util in "${utils[@]}"; do
+        test -f "${TEST_DIR}/${util}" && rm "${TEST_DIR}/${util}"
+        ln -s "$(command -v "${util}")" "${TEST_DIR}/${util}"
+    done
+
+    PATH="${TEST_DIR}" \
+        add-synced-lyrics \
+        --dir "${TEST_DIR}" \
+        --dry-run "$@"
+}
+
+test_determine_inputs_bash_recurse() {
+    test_determine_inputs_bash --recurse
+}
+
+test_determine_inputs_find() {
+    TEST_ADD_BIN='find' test_determine_inputs_bash
+}
+
+test_determine_inputs_find_recurse() {
+    TEST_ADD_BIN='find' test_determine_inputs_bash_recurse
+}
+
+test_file_dry() {
+    setup_test_data
+    add-synced-lyrics --file "${GOOD_SONG}" --dry-run
 }
 
 test_directory_dry() {
-    "${PROG}" --dir "${TEST_DIR}" --dry-run || return 1
-
-    return 0
+    setup_test_data
+    add-synced-lyrics --dir "${TEST_DIR}" --dry-run
 }
 
 test_directory_recurse_dry() {
-    "${PROG}" --dir "${TEST_DIR}" --recurse --dry-run || return 1
+    setup_test_data
+    add-synced-lyrics --dir "${TEST_DIR}" --recurse --dry-run
+}
+
+test_good_file() {
+    setup_test_data
+    add-synced-lyrics --file "${GOOD_SONG}" --debug
+    test -f "${GOOD_LYRICS}"
+}
+
+test_good_file_embed() {
+    test_good_file
+    # rm "${GOOD_LYRICS}"
+    add-synced-lyrics --file "${GOOD_SONG}" --embed
+    run_test_cmd \
+        1 \
+        test -f "${GOOD_LYRICS}"
+
+    # do it again to test that embedded is picked up and valid
+    run_test_cmd \
+        0 \
+        add-synced-lyrics --file "${GOOD_SONG}" --embed
+    [[ "${CMD_OUTPUT}" == *'already has lyrics, skipping'* ]]
+}
+
+test_bad_file() {
+    setup_test_data
+    run_test_cmd \
+        1 \
+        add-synced-lyrics \
+        --file "${BAD_SONG}" \
+        --debug
+    run_test_cmd \
+        1 \
+        test -f "${BAD_LYRICS}"
+}
+
+test_directory_recurse() {
+    setup_test_data
+    # this test should fail since it includes the bad file
+    run_test_cmd \
+        1 \
+        add-synced-lyrics --dir "${TEST_DIR}" --recurse
+}
+
+test_directory_recurse_ignore() {
+    setup_test_data
+    run_test_cmd \
+        1 \
+        add-synced-lyrics --dir "${TEST_DIR}" --recurse --ignore
+    test -f "${GOOD_LYRICS}"
+    run_test_cmd \
+        1 \
+        test -f "${BAD_LYRICS}"
 
     return 0
 }
 
-test_file() {
-    "${PROG}" --file "${TEST_FILE_1}" || return 1
-    test -f "${TEST_FILE_1//.opus/.lrc}"
+test_not_music_file() {
+    local notMusicFile="${TEST_DIR}/dummy.txt"
+    test -f "${notMusicFile}" || touch "${notMusicFile}"
+
+    run_test_cmd \
+        1 \
+        add-synced-lyrics --file "${notMusicFile}"
+
+    [[ "${CMD_OUTPUT}" == *'is not a music file'* ]]
 }
 
-test_directory_recurse() {
-    "${PROG}" --dir "${TEST_DIR}" --recurse || return 1
-    test -f "${TEST_FILE_2//.opus/.lrc}"
+test_missing_utils() {
+    test -d "${TEST_DIR}" || setup_test_data
+
+    for bin in bash readlink; do
+        test -f "${TEST_DIR}/${bin}" && rm "${TEST_DIR}/${bin}"
+        ln -s "$(command -v ${bin})" "${TEST_DIR}/${bin}"
+    done
+
+    # chmod +x "${TEST_DIR}/bash"
+    PATH="${TEST_DIR}" run_test_cmd \
+        1 \
+        add-synced-lyrics
+
+    [[ "${CMD_OUTPUT}" == *'missing node'* ]]
 }
 
 setup_test_data() {
     test -d "${TEST_DIR}" && rm -rf "${TEST_DIR}"
-    mkdir -p "${TEST_DIR}/subdir" || return 1
+    mkdir -p "${TEST_DIR}/subdir"
     ffmpegCmd=(
         ffmpeg
         -hide_banner
@@ -96,51 +299,150 @@ setup_test_data() {
         -i anullsrc=channel_layout=stereo:sample_rate=48000
         -c:a libopus
         -t 5
-        -metadata ALBUM="Messengers"
-        -metadata ARTIST="August Burns Red"
     )
     "${ffmpegCmd[@]}" \
-        -metadata TITLE="Back Burner" \
-        "${TEST_FILE_1}" || return 1
+        -metadata ISRC=${GOOD_ISRC} \
+        "${GOOD_SONG}"
     "${ffmpegCmd[@]}" \
-        -metadata TITLE="Composure" \
-        "${TEST_FILE_2}" || return 1
+        -metadata ISRC=${BAD_ISRC} \
+        "${BAD_SONG}"
 }
 
 TESTS=(
-    setup_test_data
+    test_help_option
     test_determine_inputs
     test_determine_inputs_recurse
+    test_determine_inputs_bash
+    test_determine_inputs_bash_recurse
+    test_determine_inputs_find
+    test_determine_inputs_find_recurse
+    test_not_music_file
     test_bad_input
     test_directory_dry
     test_directory_recurse_dry
     test_file_dry
-    test_file
+    test_good_file
+    test_good_file_embed
+    test_bad_file
     test_directory_recurse
+    test_directory_recurse_ignore
+    test_missing_utils
 )
 
 # make sure no test is accidentally missed
 while read -r line; do
-    IFS=' ' read -r _ _ test <<<"${line}"
-    if [[ "${TESTS[*]}" != *"${test}"* ]]; then
-        echo "missing ${test} from \$TESTS"
+    IFS=' ' read -r _ _ function <<<"${line}"
+    if [[ "${TESTS[*]}" != *"${function}"* &&
+        "${function}" == 'test_'* ]]; then
+        echo "missing ${function} from \$TESTS"
         exit 1
     fi
 done <<<"$(declare -F)"
 
-for test in "${TESTS[@]}"; do
-    if ! testOutput="$(
-        (
-            set -x
-            "${test}"
-        ) 2>&1
-    )"; then
-        echo "!! ${test} failed !!"
-        echo "${testOutput}"
-        exit 1
-    else
-        echo "${test} passed"
+# generate the coverage function for use with eval
+# to not redefine constants
+gen_coverage_function() {
+    # shellcheck disable=SC2016
+    echo 'coverage_function () {
+    local source line
+    source="${BASH_SOURCE[1]}" '"
+    source=\"\${source//'${PROGDIR}/'/}\" "'
+    line="${BASH_LINENO[0]}"
+    if [[ "${source}" == *".sh" &&
+        "${source}" != *"'"${PROGNAME}"'" ]]; then
+        {
+            # minus one because shebang is not included
+            echo "${source} $((line - 1))"' ">>${COVERAGE_FILE}" '
+        }
     fi
-done
+}'
+}
 
-exit 0
+setup_coverage() {
+    test -d "${COVERAGE_DIR}" && rm -rf "${COVERAGE_DIR}"
+    mkdir "${COVERAGE_DIR}"
+    : >"${COVERAGE_FILE}"
+    eval "$(gen_coverage_function)"
+}
+
+add-synced-lyrics() {
+    export -f coverage_function
+    PS4='$(coverage_function)' bash -x "${PROG}" "$@"
+}
+
+line_is_covered() {
+    local line="$1"
+    local lineNum="$2"
+
+    # empty lines are covered
+    [[ "${#line}" -eq 0 ]] && return 0
+
+    # commented lines are covered
+    read -r firstToken _ <<<"${line}"
+    [[ "${firstToken}" == '#'* ]] && return 0
+
+    # line is explicitly in coverage file is covered
+    grep -q "${coverageFile} ${lineNum}" "${COVERAGE_FILE}" && return 0
+
+    return 1
+}
+
+analyze_coverage() {
+    sort -u "${COVERAGE_FILE}" >"${COVERAGE_FILE}.tmp"
+    mv "${COVERAGE_FILE}.tmp" "${COVERAGE_FILE}"
+
+    mapfile -t coverageFiles < <(cut -d ' ' -f1 "${COVERAGE_FILE}" | sort -u)
+
+    local RED='\e[0;31m' GREEN='\e[0;32m' NC='\e[0m'
+
+    local fileDir fileLen color line linesCovered
+    for coverageFile in "${coverageFiles[@]}"; do
+        fileDir="${COVERAGE_DIR}/$(bash_dirname "${coverageFile}")"
+        test -d "${fileDir}" || mkdir -p "${fileDir}"
+        mapfile -t fileContents <"${coverageFile}"
+        fileLen="${#fileContents[@]}"
+        linesCovered=0
+        {
+            for ((line = 0; line < fileLen; line++)); do
+                if line_is_covered "${fileContents[${line}]}" "${line}"; then
+                    color="${GREEN}"
+                    linesCovered=$((linesCovered + 1))
+                else
+                    color="${RED}"
+                fi
+                printf '%b%s%b\n' \
+                    "${color}" \
+                    "${fileContents[${line}]}" \
+                    "${NC}"
+            done
+        } >"${COVERAGE_DIR}/${coverageFile}"
+        echo "${coverageFile} lines covered: $((linesCovered * 100 / fileLen))%"
+    done
+}
+
+if [[ $# -eq 0 ]]; then
+    setup_coverage
+
+    for test in "${TESTS[@]}"; do
+        if ! testOutput="$(
+            (
+                set -x
+                "${test}"
+            ) 2>&1
+        )"; then
+            echo
+            echo "!! ${test} failed !!"
+            echo "${testOutput}"
+            exit 1
+        else
+            echo "${test} passed"
+        fi
+    done
+
+    echo
+    analyze_coverage
+else
+    setup_coverage
+    "$@"
+    exit $?
+fi