commented sh files

src/main.sh

@@ -110,7 +110,7 @@ case "${1:-}" in
   "$VIEW_LIST_ARTISTS") list_local_artists ;;
   "$VIEW_LIST_ALBUMS") list_local_releasegroups ;;
   "$VIEW_PLAYLIST") list_playlist ;;
-  "$VIEW_SEARCH_ARTIST" | "$VIEW_SEARCH_ALBUM") fzf_reload_after_change ;;
+  "$VIEW_SEARCH_ARTIST" | "$VIEW_SEARCH_ALBUM") mb_results_async ;;
   esac
   exit 0
   ;;
@@ -298,7 +298,7 @@ case "${1:-}" in
   # This stops any search being executed and initiates a new query through the
   # MusicBrainz API. The results will be made available through the ``--lines
   # <view>`` command.
-  fzf_handle_change "$2"
+  mb_search_async "$2"
   exit 0
   ;;
 "--preview-artist")
@@ -308,7 +308,7 @@ case "${1:-}" in
   #
   # This prints the text to be displayed in the preview window for the
   # specified artist.
-  __preview_artist "$2"
+  preview_artist "$2"
   exit 0
   ;;
 esac

src/sh/api.sh

@@ -1,3 +1,10 @@
+# This file provides the methods for access to several APIs
+#
+# APIs:
+# - MusicBrainz
+# - Discogs
+# - Wikidata
+# - Wikipedia
 if [ ! "${API_LOADED:-}" ]; then
   MB_MAX_RETRIES=10
   MB_BROWSE_STEPS=100
@@ -8,6 +15,16 @@ if [ ! "${API_LOADED:-}" ]; then
   export API_LOADED=1
 fi
 
+# Internal method for MusicBrainz API access
+#
+# @argument $1: entity (see `case` below)
+# @argument $2: MusicBrainz ID
+# @argument $3: offset (optional, but mandatory for browse requests)
+#
+# If the API access fails, then the error message is logged, and at most
+# `MB_MAX_RETRIES` retries are made. If browse requests are made, then at most
+# `MB_BROWSE_STEPS` number of entries are requested per call. The offset in
+# browse request must be specified.
 __api_mb() {
   tmpout=$(mktemp)
   for _ in $(seq "$MB_MAX_RETRIES"); do
@@ -98,35 +115,62 @@ __api_mb() {
   return 1
 }
 
+# The interface to MusicBrainz API.
+
+# Retrieve MusicBrainz artist information
+#
+# @argument $1: MusicBrainz artist ID
 api_mb_artist() {
   __api_mb "artist" "$1"
 }
 
+# Retrieve MusicBrainz release-group information
+#
+# @argument $1: MusicBrainz release-group ID
 api_mb_releasegroup() {
   __api_mb "releasegroup" "$1"
 }
 
+# Retrieve MusicBrainz release information
+#
+# @argument $1: MusicBrainz release ID
 api_mb_release() {
   __api_mb "release" "$1"
 }
 
+# Retrieve MusicBrainz release-groups for given artist
+#
+# @argument $1: MusicBrainz artist ID
+# @argument $2: offset (defaults to 0)
 api_mb_browse_artist_releasegroups() {
   __api_mb "browse-artist-releasegroups" "$1" "${2:-0}"
 }
 
+# Retrieve MusicBrainz releases in given release group
+#
+# @argument $1: MusicBrainz release-group ID
+# @argument $2: offset (defaults to 0)
 api_mb_browse_releasegroup_releases() {
   __api_mb "browse-releasegroup-releases" "$1" "${2:-0}"
 }
 
-# Argument: Search string
+# Search MusicBrainz database for given artist
+#
+# @argument $1: query
 api_mb_search_artist() {
   __api_mb "search-artist" "$1"
 }
 
+# Search MusicBrainz database for given release group
+#
+# @argument $1: query
 api_mb_search_releasegroup() {
   __api_mb "search-releasegroup" "$1"
 }
 
+# Retrieve Discogs artist information
+#
+# @argument $1: Discogs artist ID
 api_discogs_artist() {
   $CURL \
     --get \
@@ -134,6 +178,9 @@ api_discogs_artist() {
     "https://api.discogs.com/artists/$1"
 }
 
+# Retrieve sitelinks from wikidata
+#
+# @argument $1: Wikidata ID
 api_wikidata_sitelinks() {
   $CURL \
     --get \
@@ -141,6 +188,9 @@ api_wikidata_sitelinks() {
     "https://www.wikidata.org/w/rest.php/wikibase/v1/entities/items/$1/sitelinks"
 }
 
+# Retrieve summary from Wikipedia page
+#
+# @argument $1: Wikipedia page name
 api_wikipedia_en_summary() {
   $CURL \
     --get \

src/sh/awk.sh

@@ -1,3 +1,5 @@
+# The code below is used together with `scripts/build.sh`to internalize the awk
+# scripts. See the awk sources for more information.
 if [ ! "${AWK_LOADED:-}" ]; then
   AWK_ARTISTS=$(
     cat <<'EOF'

src/sh/cache.sh

@@ -1,17 +1,27 @@
-# Caching structure
+# This implements the caching functionalities. The cache is stored under
-#
+# `CACHEDIR` defined below, and organized as follows (all paths relative to
-# ./artist/radix(uuid)/musicbrainz.json         # Artist information
+# `CAHCEDIR`) ./<type>/radix(mbid)/<file>. Here, type is one of `TYPE_ARTIST`,
-# ./artist/radix(uuid)/releasegroups.json       # List of all release groups
+# `TYPE_RELEASEGROUP`, or `TYPE_RELEASE`. The string `radix(mbid)` is the radix
-# ./artist/radix(uuid)/...                      # Any other artist information
+# encoded MusicBrainz ID of given type (see method below). Finally <file> is a
-# ./releasegroup/radix(uuid)/musicbrainz.json   # Release group information
+# filename to hold the respective data in the json format. Currently, the data
-# ./releasegroup/radix(uuid)/releases.json      # List of all releases in release group
+# is stored as follows:
-# ./release/radix(uuid)/musicbrainz.json        # Release information with tracklist etc.
+# ./artist/radix(mbid)/musicbrainz.json         MusicBrainz artist data
+# ./artist/radix(mbid)/discogs.json             Discogs artist data
+# ./artist/radix(mbid)/wikidata.json            Wikidata artist data
+# ./artist/radix(mbid)/enwikipedia.json         Wikipedia artist data
+# ./artist/radix(mbid)/releasegroups.json       Release groups of artist
+# ./releasegroup/radix(mbid)/musicbrainz.json   MusicBrainz release-group data
+# ./releasegroup/radix(mbid)/releases.json      Releases in release group
+# ./release/radix(mbid)/musicbrainz.json        MusicBrainz release data
 
 if [ ! "${CACHE_LOADED:-}" ]; then
+  # Base path for cache
   CACHEDIR="$HOME/.cache/$APP_NAME"
+  # Directory names for cache types
   TYPE_ARTIST="artist"
   TYPE_RELEASEGROUP="releasegroup"
   TYPE_RELEASE="release"
+  # Filenames for cache entries
   ARTIST_FILENAME="musicbrainz.json"
   ARTIST_RELEASEROUPS_FILENAME="releasegroups.json"
   ARTIST_DISCOGS_FILENAME="discogs.json"
@@ -28,17 +38,22 @@ if [ ! "${CACHE_LOADED:-}" ]; then
   export CACHE_LOADED=1
 fi
 
-# Radix transform directory name
+# Radix transform string
+#
+# @argument $1: some string
 __radix() {
   echo "$1" | awk -F "" '{ print $1$2$3$4"/"$5$6$7$8"/"$0 }'
 }
 
-# Radix transform directory names from stdin
+# Radix transform strings (batch)
+#
+# Here, the input is read line-by-line from stdin.
 __radix_batch() {
   cat | awk -F "" '{ print $1$2$3$4"/"$5$6$7$8"/"$0 }'
 }
 
-# Super wrapper
+# Super wrapper to print json data from cache
+#
 # argument $1: type
 # argument $2: MusicBrainz ID
 # argument $3: Filename of json file
@@ -48,7 +63,8 @@ __get_json() {
   cat "$f"
 }
 
-# Super wrapper
+# Super wrapper to store json data in cache
+#
 # argument $1: type
 # argument $2: MusicBrainz ID
 # argument $3: Filename of json file
@@ -61,35 +77,64 @@ __put_json() {
   [ -s "$tmpf" ] && mv "$tmpf" "$f" || printf "{}" >"$f"
 }
 
-## Artist
+# Print MusicBrainz data of given artist from cache
+#
+# @argument $1: MusicBrainz artist ID
 cache_get_artist() {
   __get_json "$TYPE_ARTIST" "$1" "$ARTIST_FILENAME"
 }
 
+# Print release groups (MusicBrainz) of given artist from cache
+#
+# @argument $1: MusicBrainz artist ID
 cache_get_artist_releasegroups() {
   __get_json "$TYPE_ARTIST" "$1" "$ARTIST_RELEASEROUPS_FILENAME"
 }
 
+# Print Discogs data of given artist from cache
+#
+# @argument $1: MusicBrainz artist ID
 cache_get_artist_discogs() {
   __get_json "$TYPE_ARTIST" "$1" "$ARTIST_DISCOGS_FILENAME"
 }
 
+# Print Wikipedia data of given artist from cache
+#
+# @argument $1: MusicBrainz artist ID
 cache_get_artist_enwikipedia() {
   __get_json "$TYPE_ARTIST" "$1" "$ARTIST_ENWIKIPEDIA_FILENAME"
 }
 
+# Print Wikidata data of given artist from cache
+#
+# @argument $1: MusicBrainz artist ID
 cache_get_artist_wikidata() {
   __get_json "$TYPE_ARTIST" "$1" "$ARTIST_WIKIDATA_FILENAME"
 }
 
+# Store MusicBrainz data of given artist in cache
+#
+# @argument $1: MusicBrainz artist ID
+#
+# This methods reads the data to be stored from stdin.
 cache_put_artist() {
   cat | __put_json "$TYPE_ARTIST" "$1" "$ARTIST_FILENAME"
 }
 
+# Store release groups (MusicBrainz) of given artist in cache
+#
+# @argument $1: MusicBrainz artist ID
+#
+# This methods reads the data to be stored from stdin.
 cache_put_artist_releasegroups() {
   cat | __put_json "$TYPE_ARTIST" "$1" "$ARTIST_RELEASEROUPS_FILENAME"
 }
 
+# Append release groups (MusicBrainz) of given artist to existing file in cache
+#
+# @argument $1: MusicBrainz artist ID
+#
+# This methods reads the data to be stored from stdin.
 cache_append_artist_releasegroups() {
   tmpf=$(mktemp)
   cat >"$tmpf"
@@ -99,35 +144,59 @@ cache_append_artist_releasegroups() {
   rm -f "$tmpf"
 }
 
+# Store Discogs data of given artist to cache
+#
+# @argument $1: MusicBrainz artist ID
 cache_put_artist_discogs() {
   cat | __put_json "$TYPE_ARTIST" "$1" "$ARTIST_DISCOGS_FILENAME"
 }
 
+# Store Wikipedia data of given artist to cache
+#
+# @argument $1: MusicBrainz artist ID
 cache_put_artist_enwikipedia() {
   cat | __put_json "$TYPE_ARTIST" "$1" "$ARTIST_ENWIKIPEDIA_FILENAME"
 }
 
+# Store Wikidata data of given artist to cache
+#
+# @argument $1: MusicBrainz artist ID
 cache_put_artist_wikidata() {
   cat | __put_json "$TYPE_ARTIST" "$1" "$ARTIST_WIKIDATA_FILENAME"
 }
 
-## Release group
+# Print MusicBrainz data of given release group from cache
+#
+# @argument $1: MusicBrainz release-group ID
 cache_get_releasegroup() {
   __get_json "$TYPE_RELEASEGROUP" "$1" "$RELEASEGROUP_FILENAME"
 }
 
+# Print releases (MusicBrainz) in release group from cache
+#
+# @argument $1: MusicBrainz release-group ID
 cache_get_releasegroup_releases() {
   __get_json "$TYPE_RELEASEGROUP" "$1" "$RELEASEGROUP_RELEASES_FILENAME"
 }
 
+# Store MusicBrainz data of given release group in cache
+#
+# @argument $1: MusicBrainz release-group ID
 cache_put_releasegroup() {
   cat | __put_json "$TYPE_RELEASEGROUP" "$1" "$RELEASEGROUP_FILENAME"
 }
 
+# Store releases (MusicBrainz) of given release group in cache
+#
+# @argument $1: MusicBrainz release-group ID
 cache_put_releasegroup_releases() {
   cat | __put_json "$TYPE_RELEASEGROUP" "$1" "$RELEASEGROUP_RELEASES_FILENAME"
 }
 
+# Append releases (MusicBrainz) of given release group to existing file in
+# cache
+#
+# @argument $1: MusicBrainz release-group ID
 cache_append_releasegroup_releases() {
   tmpf=$(mktemp)
   cat >"$tmpf"
@@ -137,40 +206,26 @@ cache_append_releasegroup_releases() {
   rm -f "$tmpf"
 }
 
-## Release
+# Print MusicBrainz data of given release from cache
+#
+# @argument $1: MusicBrainz release ID
 cache_get_release() {
   __get_json "$TYPE_RELEASE" "$1" "$RELEASE_FILENAME"
 }
 
+# Store MusicBrainz data of given release in cache
+#
+# @argument $1: MusicBrainz release ID
 cache_put_release() {
   cat | __put_json "$TYPE_RELEASE" "$1" "$RELEASE_FILENAME"
 }
 
-## Cache deletion
+# Print all MusicBrainz cache paths to the files specified by their IDs
-cache_delete_artist() {
-  # Get release groups
-  echo "NOT IMPLEMENTED" >/dev/stderr
-}
-
-# Check if main items are in cache
-# argument $1: type
-# argument $2: MusicBrainz ID
-in_cache() {
-  case "$1" in
-  "$TYPE_ARTIST") fn="$ARTIST_FILENAME" ;;
-  "$TYPE_RELEASEGROUP") fn="$RELEASEGROUP_FILENAME" ;;
-  "$TYPE_RELEASE") fn="$RELEASE_FILENAME" ;;
-  *) return 1 ;;
-  esac
-  [ "$(__get_json "$1" "$2" "$fn")" ] && return 0 || return 1
-}
-
-# Print all cache paths to the files specified by their IDs
 #
 # @argument $1: type
 #
 # This method reads from stdin any number of MusicBrainz IDs of objects of the
-# specified type, and prints the file pahts.
+# specified type, and prints the file paths.
 cache_get_file_batch() {
   case "$1" in
   "$TYPE_ARTIST") fn="$ARTIST_FILENAME" ;;

src/sh/config.sh

@@ -1,4 +1,16 @@
-# Configuration capabilities
+# Main application configuration. This application does not require a
+# configuration file. However, a configuration file may be stored as
+# `CONFIGFILE_DEFAULT`. If that file exists, it will be sourced. The path to
+# the file may be overwritten by specifying the environment variable
+# `CONFIGFILE`. If a configuration file is specified, then it must also exist.
+# A configuration file comprises the specification of environment variables
+# that are` allowed to be set.
+#
+# Currently, the following files hold variables that are configurable:
+# - `src/sh/filter.sh`:  Configuration of filters that can be triggered with
+#                        the respective key bindings.
+# - `src/sh/keys.sh`:    Configuration of key bindings to certain actions
+# - `src/sh/theme.sh`:   Configuration of theme
 CONFIGFILE_DEFAULT="$HOME/.config/$APP_NAME/config"
 CONFIGFILE="${CONFIGFILE:-"$CONFIGFILE_DEFAULT"}"
 [ "$CONFIGFILE" != "$CONFIGFILE_DEFAULT" ] && [ ! -f "$CONFIGFILE" ] && err "The configuration file manually specified with the environment variable CONFIGFILE=($CONFIGFILE) does not exist." && exit 1

src/sh/filter.sh

@@ -1,7 +1,14 @@
-# Preset filters
+# Preset filters for different views. These filters are associated to key
-#
+# bindings (see `src/sh/keys.sh`), and are configurable through a configuration
-# See `src/sh/query.sh` for details and the associated methods.
+# file (see `src/sh/config.sh`).
+
+# The `QUERY_LOCAL` filter is associated with the keys `KEYS_FILTER_LOCAL`. It
+# is used to hide all entries that are not available locally (see
+# `src/sh/query.sh` for details and the relevant methods)
 QUERY_LOCAL="${QUERY_LOCAL:-"$(printf "'%s'" "$FORMAT_LOCAL" | __clean_filter)"}"
+
+# The following variables store preset strings derived from the theme (see
+# `src/sh/theme.sh`), and used in the assignment of the default filters.
 q_has_seconary="$(printf "$FORMAT_TYPE_HAS_SECONDARY" "" | __clean_filter)"
 q_album="$(printf "%s" "$FORMAT_TYPE_ALBUM" | __clean_filter)"
 q_ep=$(printf "%s" "$FORMAT_TYPE_EP" | sed "s/${ESC}\[[0-9;]*[mK]//g" | sed "s/ /\\\ /g")
@@ -11,6 +18,9 @@ if printf "$RV_FORMAT" | grep -q "<<status>>"; then
 fi
 export QUERY_LOCAL
 
+# Here starts the list of all filters (grouped per view) that are associated to
+# the keys `KEYS_FILTER_0` - `KEYS_FILTER_9`. The filters in the `F_1_<view>`
+# variable are automatically applied whenever the given view is entered.
 F_1_VIEW_ARTIST="${F_1_VIEW_ARTIST:-"!'$q_has_seconary'"}"
 F_2_VIEW_ARTIST="${F_2_VIEW_ARTIST:-"'$q_album'"}"
 F_3_VIEW_ARTIST="${F_3_VIEW_ARTIST:-"'$q_ep'"}"

src/sh/fzf.sh

@@ -1,4 +1,5 @@
-# Print the command that sets the header.
+# Print the fzf instructions that sets the header
+#
 # @argument $1: view
 # @argument $2: mbid
 fzf_command_set_header() {
@@ -30,93 +31,3 @@ fzf_command_set_header() {
   esac
   printf "+change-header(%s)" "${header:-"???"}"
 }
-
-# Reload hook that is used after change in query
-fzf_reload_after_change() {
-  # Wait for async. process to terminate
-  sleep 1
-  while [ -f "$LOCKFILE" ]; do
-    sleep 1
-  done
-  # Show results
-  column -t -s "$(printf '\t')" "$RESULTS" |
-    sed 's| \+\([0-9a-f-]\+\) \+\([0-9a-f-]\+\)$|\t\1\t\2|'
-}
-
-# Handle change in query
-fzf_handle_change() {
-  view="$1"
-  # Kill any running search
-  if [ -f "$PIDFILE" ]; then
-    pid=$(cat "$PIDFILE")
-    rm -f "$PIDFILE"
-    kill -9 "$pid" >/dev/null 2>&1 || true
-  fi
-  # Stop, if no search string is given
-  [ "$FZF_QUERY" ] || exit 0
-  # Store PID of current process
-  echo "$$" >"$PIDFILE"
-  touch "$LOCKFILE"
-  sleep 1
-  if [ "$view" = "$VIEW_SEARCH_ARTIST" ]; then
-    api_mb_search_artist "$FZF_QUERY" |
-      $JQ '.artists[] | [
-    .id,
-    .type,
-    .name,
-    .disambiguation,
-    .["life-span"].begin,
-    .["life-span"].end
-    ] | join("\t")' |
-      awk \
-        -F "\t" \
-        -v file_local_artists="${LOCALDATA_ARTISTS:-}" \
-        -v format_person="$AV_PERSON" \
-        -v format_group="$AV_GROUP" \
-        -v format_disambiguation="$AV_DISAMBIGUATION" \
-        -v format_local="$FORMAT_LOCAL" \
-        "$AWK_ARTISTS" >"$RESULTS" ||
-      true
-  else
-    api_mb_search_releasegroup "$FZF_QUERY" |
-      $JQ '."release-groups"[] | [ 
-    .id,
-    ."primary-type",
-    (."secondary-types" // []|join(";")),
-    ."first-release-date",
-    .title,
-    (."artist-credit" | map(([.name, .joinphrase]|join(""))) | join(""))
-    ] | join("\t")' |
-      awk \
-        -F "\t" \
-        -v file_local_releasegroups="${LOCALDATA_RELEASEGROUPS:-}" \
-        -v format_release="$RGV_RELEASE" \
-        -v format_release_w_artist="$RGV_RELEASE_W_ARTIST" \
-        -v format_year="$RGV_YEAR" \
-        -v format_album="$FORMAT_TYPE_ALBUM" \
-        -v format_single="$FORMAT_TYPE_SINGLE" \
-        -v format_ep="$FORMAT_TYPE_EP" \
-        -v format_broadcast="$FORMAT_TYPE_BROADCAST" \
-        -v format_other="$FORMAT_TYPE_OTHER" \
-        -v format_has_secondary="$FORMAT_TYPE_HAS_SECONDARY" \
-        -v format_secondary="$FORMAT_TYPE_SECONDARY" \
-        -v format_compilation="$FORMAT_TYPE_SECONDARY_COMPILATION" \
-        -v format_soundtrack="$FORMAT_TYPE_SECONDARY_SOUNDTRACK" \
-        -v format_spokenword="$FORMAT_TYPE_SECONDARY_SPOKENWORD" \
-        -v format_interview="$FORMAT_TYPE_SECONDARY_INTERVIEW" \
-        -v format_audiobook="$FORMAT_TYPE_SECONDARY_AUDIOBOOK" \
-        -v format_audiodrama="$FORMAT_TYPE_SECONDARY_AUDIODRAMA" \
-        -v format_live="$FORMAT_TYPE_SECONDARY_LIVE" \
-        -v format_remix="$FORMAT_TYPE_SECONDARY_REMIX" \
-        -v format_djmix="$FORMAT_TYPE_SECONDARY_DJMIX" \
-        -v format_mixtape="$FORMAT_TYPE_SECONDARY_MIXTAPE" \
-        -v format_demo="$FORMAT_TYPE_SECONDARY_DEMO" \
-        -v format_fieldrec="$FORMAT_TYPE_SECONDARY_FIELDREC" \
-        -v format_local="$FORMAT_LOCAL" \
-        "$AWK_RELEASEGROUPS" |
-      cut -d "$(printf '\t')" -f 2- >"$RESULTS" ||
-      true
-  fi
-  # Process ends now: Display and quit
-  rm -f "$LOCKFILE" "$PIDFILE"
-}

src/sh/lists.sh

@@ -1,5 +1,8 @@
+# These methods generate lists that are used as input to FZF.
+
 # List release groups of given artist
-# argument $1: MB artist id
+#
+# argument $1: MusicBrainz artist ID
 list_releasegroups() {
   name=$(mb_artist "$1" | $JQ '.name')
   mb_artist_releasegroups "$1" |
@@ -47,7 +50,8 @@ list_releasegroups() {
 }
 
 # List releases in given relese group
-# argument $1: MB release-group id
+#
+# argument $1: MusicBrainz release-group ID
 list_releases() {
   title="$(mb_releasegroup "$1" |
     $JQ '.title')"
@@ -92,7 +96,8 @@ list_releases() {
 }
 
 # List recordings of given release
-# argument $1: MB release id
+#
+# argument $1: MusicBrainz release ID
 list_recordings() {
   deco="$(grep "$1" "$LOCALDATA_RELEASES" | cut -d "$(printf '\t')" -f 2)"
   if [ "$deco" ]; then
@@ -131,22 +136,19 @@ list_recordings() {
   fi
 }
 
-# List artists (local)
+# List artists available locally
 list_local_artists() {
   cat "$LOCALDATA_ARTISTS_VIEW" 2>/dev/null
 }
 
-# List release groups (local)
+# List release groups vailable locally
 list_local_releasegroups() {
   cat "$LOCALDATA_RELEASEGROUPS_VIEW" 2>/dev/null
 }
 
-# List releases (local)
+# List artist from input json data
-list_local_releases() {
+#
-  cat "$LOCALDATA_RELEASES_VIEW" 2>/dev/null
+# The input is read from stdin
-}
-
-# Generate artist list from JSON
 list_artists_from_json() {
   cat |
     $JQ 'map([.artist.id, .artist.type, .name] | join("\t")) | join("\n")' |
@@ -161,7 +163,7 @@ list_artists_from_json() {
     column -t -s "$(printf '\t')" -l 2
 }
 
-# Generate playlist view
+# Print playlist currently loaded
 list_playlist() {
   count=$(mpv_playlist_count)
   [ "$count" -eq 0 ] && return 0

src/sh/local.sh

@@ -1,3 +1,8 @@
+# Database functionality to support local music.
+#
+# All local data is stored in the directory `LOCALDATADIR`. In the future, we
+# will also use the methods here, and modifications thereof, to support
+# MusicBainz collections.
 if [ ! "${LOCAL_LOADED:-}" ]; then
   LOCALDATADIR="$HOME/.cache/$APP_NAME/local"
   LOCALDATA_ARTISTS="$LOCALDATADIR/artists"
@@ -19,7 +24,13 @@ if [ ! "${LOCAL_LOADED:-}" ]; then
   export LOCAL_LOADED=1
 fi
 
-gettags() {
+# Retrieve tags as json object from music file
+#
+# @argument $1: path to music file
+#
+# The tags retrieved are the MusicBrainz release ID and the MusicBrainz track
+# ID
+__gettags() {
   ffprobe -v error -show_entries format_tags -print_format json "$1" |
     $JQ '.format.tags | {
       trackid: (."MusicBrainz Release Track Id" // ."MUSICBRAINZ_RELEASETRACKID" // ."MusicBrainz/Release Track Id" // ""),
@@ -27,9 +38,14 @@ gettags() {
     }'
 }
 
-# Read music files in specified directory and create json file that points to
+# Decorate locally available music
-# all relevant MusicBrainz IDs.
+#
 # @input $1: Path to directory with album
+#
+# This methods reads the music files in the specified directory and writes a
+# json file that points to all relevant MusicBrainz IDs. If the directory
+# contains untagged files, or files of different releases, then the decoration
+# process will fail, and an error is printed.
 decorate() {
   if [ -f "$1/$DECORATION_FILENAME" ]; then
     info "Directory $1 has already been decorated (skipping)"
@@ -39,7 +55,7 @@ decorate() {
   tmpf=$(mktemp)
   (cd "$1" && find . -type f -iname '*.mp3' -o -iname '*.mp4' -o -iname '*.flac' -o -iname '*.m4a') >"$tmpf"
   while IFS= read -r f; do
-    mbid=$(gettags "$1/$f")
+    mbid=$(__gettags "$1/$f")
     rid=$(echo "$mbid" | $JQ '.releaseid')
     tid=$(echo "$mbid" | $JQ '.trackid')
     if [ ! "$rid" ] || [ ! "$tid" ]; then
@@ -105,7 +121,13 @@ __batch_load_missing() {
   rm -f "$tmpf"
 }
 
-# Precompute views
+# Precompute lists
+#
+# The main views (VIEW_ARTIST and TYPE_RELEASEGROUP) for locally available
+# music are theme dependent. These views are generated from the lists that are
+# produced with the present method. It contains all essential data, but in a
+# theme-independent fashion. The lists are stored in the files
+# `LOCALDATA_ARTISTS_LIST` and `LOCALDATA_RELEASEGROUPS_LIST`.
 __precompute_lists() {
   cache_get_file_batch "$TYPE_ARTIST" <"$LOCALDATA_ARTISTS" | xargs \
     $JQ '[
@@ -125,23 +147,13 @@ __precompute_lists() {
       .title,
       (."artist-credit" | map(([.name, .joinphrase]|join(""))) | join(""))
       ] | join("\t")' >"$LOCALDATA_RELEASEGROUPS_LIST"
-  #  cache_get_file_batch "$TYPE_RELEASE" <"$LOCALDATA_RELEASES" | xargs \
-  #    $JQ '[
-  #      .id,
-  #      .status,
-  #      .date,
-  #      ."cover-art-archive".count,
-  #      (."label-info" | map(.label.name) | unique | join(", ")),
-  #      (.media | map(."track-count") | add),
-  #      (.media | map(.format) | unique | join(", ")),
-  #      .country,
-  #      .title,
-  #      (."artist-credit" | map(([.name, .joinphrase]|join(""))) | join(""))
-  #      ] | join("\t")' >"$LOCALDATA_RELEASES_LIST" &
 }
 
 # Precompute views
-# TODO: The sed opperations take too long, improve!
+#
+# This method injects the theme elements to the lists from `precompute_lists`.
+# The resulting views are stored in the files `LOCALDATA_ARTISTS_VIEW` and
+# `LOCALDATA_RELEASEGROUPS_VIEW`.
 precompute_views() {
   awk \
     -F "\t" \
@@ -193,7 +205,9 @@ precompute_views() {
 # argument $1: path to decorated music files
 #
 # This method parses all decorations and generates a line-by-line database of
-# locally available artists, releases, and release groups.
+# locally available artists, releases, and release groups. This data is stored
+# in the files `LOCALDATA_ARTISTS`, `LOCALDATA_RELEASES`, and
+# `LOCALDATA_RELEASEGROUPS`.
 reloaddb() {
   rm -rf "$LOCALDATADIR"
   mkdir -p "$LOCALDATADIR"
@@ -225,16 +239,24 @@ reloaddb() {
 }
 
 # Check if necessary cache files are present or not
+#
+# This method returns a non-zero value if some cached file is required to exist
+# for the computation of the lists (and views). This does not include the
+# derivation of the MusicBrainz artist IDs and MusicBrainz release-group IDs
+# from the MusicBrainz releases (see the `reloaddb` method above).
 local_files_present() {
   cache_get_file_batch "$TYPE_ARTIST" <"$LOCALDATA_ARTISTS" | xargs ls >/dev/null 2>&1 || return 1
   cache_get_file_batch "$TYPE_RELEASEGROUP" <"$LOCALDATA_RELEASEGROUPS" | xargs ls >/dev/null 2>&1 || return 1
-  cut -d "$(printf '\t')" -f 1 "$LOCALDATA_RELEASES" | cache_get_file_batch "$TYPE_RELEASEGROUP" | xargs ls >/dev/null 2>&1 || return 1
+  #cut -d "$(printf '\t')" -f 1 "$LOCALDATA_RELEASES" | cache_get_file_batch "$TYPE_RELEASE" | xargs ls >/dev/null 2>&1 || return 1
   return 0
 }
 
 # Load missing files
+#
+# If missing files were detected with `local_files_present`, then these missing
+# files may be cached using the present method.
 load_missing_files() {
   __batch_load_missing "$TYPE_ARTIST" <"$LOCALDATA_ARTISTS"
   __batch_load_missing "$TYPE_RELEASEGROUP" <"$LOCALDATA_RELEASEGROUPS"
-  cut -d "$(printf '\t')" -f 1 "$LOCALDATA_RELEASES" | __batch_load_missing "$TYPE_RELEASE"
+  #cut -d "$(printf '\t')" -f 1 "$LOCALDATA_RELEASES" | __batch_load_missing "$TYPE_RELEASE"
 }

src/sh/log.sh

@@ -1,4 +1,7 @@
 # Logging methods
+#
+# The default log file is `LOGFILE`. In the future, this file may become
+# configurable.
 if [ ! "${LOG_LOADED:-}" ]; then
   ERR="\033[38;5;196m"
   INFO="\033[38;5;75m"
@@ -11,10 +14,14 @@ if [ ! "${LOG_LOADED:-}" ]; then
   export LOG_LOADED=1
 fi
 
+# Print an error message to stderr and log it incuding the time stamp and PID
+# to the log file.
 err() {
   echo "$(date) [$$]>${ERR}ERROR:${OFF} ${1:-}" | tee -a "$LOGFILE" | cut -d ">" -f 2- >/dev/stderr
 }
 
+# Print information to stderr and log it incuding the time stamp and PID to the
+# log file.
 info() {
   echo "$(date) [$$]>${INFO}Info:${OFF} ${1:-}" | tee -a "$LOGFILE" | cut -d ">" -f 2- >/dev/stderr
 }

src/sh/mb.sh

@@ -1,7 +1,13 @@
-# The only IDs uses here are MusicBrainz IDs
+# This files provides a high-level access to the MusicBrainz databse. The only
+# IDs used here are MusicBrainz IDs
 
-# Helper methods to retrieve from cache, if it exists, and otherwise populate
+# The following methods are local methods that combines the MusicBrainz API
-# cache and retrieve
+# with the caching methods.
+
+# Retrieve MusicBrainz data for artist from cache (if it exists), and otherwise
+# download it using the MusicBrainz API.
+#
+# @argument $1: MusicBrainz artist ID
 __mb_artist_cache_or_fetch() {
   if ! cache_get_artist "$1"; then
     api_mb_artist "$1" | cache_put_artist "$1"
@@ -9,6 +15,10 @@ __mb_artist_cache_or_fetch() {
   fi
 }
 
+# Retrieve MusicBrainz data for release group from cache (if it exists), and
+# otherwise download it using the MusicBrainz API.
+#
+# @argument $1: MusicBrainz release-group ID
 __mb_releasegroup_cache_or_fetch() {
   if ! cache_get_releasegroup "$1"; then
     api_mb_releasegroup "$1" | cache_put_releasegroup "$1"
@@ -16,6 +26,10 @@ __mb_releasegroup_cache_or_fetch() {
   fi
 }
 
+# Retrieve MusicBrainz data for release from cache (if it exists), and
+# otherwise download it using the MusicBrainz API.
+#
+# @argument $1: MusicBrainz release ID
 __mb_release_cache_or_fetch() {
   if ! cache_get_release "$1"; then
     api_mb_release "$1" | cache_put_release "$1"
@@ -23,6 +37,10 @@ __mb_release_cache_or_fetch() {
   fi
 }
 
+# Retrieve MusicBrainz data for release groups of given artist from cache (if
+# it exists), and otherwise download it using the MusicBrainz API.
+#
+# @argument $1: MusicBrainz artist ID
 __mb_artist_cache_or_fetch_releasegroups() {
   if ! cache_get_artist_releasegroups "$1"; then
     api_mb_browse_artist_releasegroups "$1" | cache_put_artist_releasegroups "$1"
@@ -39,6 +57,10 @@ __mb_artist_cache_or_fetch_releasegroups() {
   fi
 }
 
+# Retrieve MusicBrainz data for releases of given release group from cache (if
+# it exists), and otherwise download it using the MusicBrainz API.
+#
+# @argument $1: MusicBrainz release-group ID
 __mb_releasegroup_cache_or_fetch_releases() {
   if ! cache_get_releasegroup_releases "$1"; then
     api_mb_browse_releasegroup_releases "$1" | cache_put_releasegroup_releases "$1"
@@ -55,14 +77,18 @@ __mb_releasegroup_cache_or_fetch_releases() {
   fi
 }
 
-# Get MusicBrainz json for artist
+# The following methods provide the external interface
-# @argument $1: MusicBrainz Artist ID
+
+# Retrieve MusicBrainz data for artist
+#
+# @argument $1: MusicBrainz artist ID
 mb_artist() {
   __mb_artist_cache_or_fetch "$1"
 }
 
-# Get Wikidata json for artist
+# Retrieve Wikidata data for artist
-# @argument $1: MusicBrainz Artist ID
+#
+# @argument $1: MusicBrainz artist ID
 mb_artist_wikidata() {
   if ! cache_get_artist_wikidata "$1"; then
     wikidataid=$(mb_artist "$1" |
@@ -76,8 +102,9 @@ mb_artist_wikidata() {
   fi
 }
 
-# Get Wikipedia (English) summary json for artist
+# Retrieve Wikipedia (English) summary json for artist
-# @argument $1: MusicBrainz Artist ID
+#
+# @argument $1: MusicBrainz artist ID
 mb_artist_enwikipedia() {
   if ! cache_get_artist_enwikipedia "$1"; then
     # To fetch the wikipedia data, we need the wikipedia URL
@@ -97,8 +124,9 @@ mb_artist_enwikipedia() {
   fi
 }
 
-# Get Discogs json for artist
+# Retrieve  Discogs json for artist
-# @argument $1: MusicBrainz Artist ID
+#
+# @argument $1: MusicBrainz artist ID
 mb_artist_discogs() {
   if ! cache_get_artist_discogs "$1"; then
     discogsid=$(mb_artist "$1" |
@@ -112,22 +140,131 @@ mb_artist_discogs() {
   fi
 }
 
-# Get release-groups json for artist
+# Retrieve release groups for artist
-# @argument $1: MusicBrainz Artist ID
+#
+# @argument $1: MusicBrainz artist ID
 mb_artist_releasegroups() {
   __mb_artist_cache_or_fetch_releasegroups "$1"
 }
 
-# Get MusicBrainz json for release group
+# Retrieve MusicBrainz release group
-# @argument $1: MusicBrainz Release-Group ID
+#
+# @argument $1: MusicBrainz release-group ID
 mb_releasegroup() {
   __mb_releasegroup_cache_or_fetch "$1"
 }
 
+# Retrieve MusicBrainz releases of release group
+#
+# @argument $1: MusicBrainz release-group ID
 mb_releasegroup_releases() {
   __mb_releasegroup_cache_or_fetch_releases "$1"
 }
 
+# Retrieve MusicBrainz release
+#
+# @argument $1: MusicBrainz release ID
 mb_release() {
   __mb_release_cache_or_fetch "$1"
 }
+
+# Reload hook that is used after a change in the query (when searching
+# MusicBrainz).
+#
+# This method waits for the search to complete, then it parses the search
+# results and prints them.
+mb_results_async() {
+  # Wait for async. process to terminate
+  sleep 1
+  while [ -f "$LOCKFILE" ]; do
+    sleep 1
+  done
+  # Show results
+  column -t -s "$(printf '\t')" "$RESULTS" |
+    sed 's| \+\([0-9a-f-]\+\) \+\([0-9a-f-]\+\)$|\t\1\t\2|'
+}
+
+# Initiate search on MusicBrainz
+#
+# @argument $1: view
+#
+# This methods initiates an asynchronous search for both views
+# (VIEW_SEARCH_ARTIST and VIEW_SEARCH_ALBUM). If a running query is detected,
+# that one is killed first. The search results are then stored and become
+# retrievable using `mb_results_async`.
+mb_search_async() {
+  view="$1"
+  # Kill any running search
+  if [ -f "$PIDFILE" ]; then
+    pid=$(cat "$PIDFILE")
+    rm -f "$PIDFILE"
+    kill -9 "$pid" >/dev/null 2>&1 || true
+  fi
+  # Stop, if no search string is given
+  [ "$FZF_QUERY" ] || exit 0
+  # Store PID of current process
+  echo "$$" >"$PIDFILE"
+  touch "$LOCKFILE"
+  sleep 1
+  if [ "$view" = "$VIEW_SEARCH_ARTIST" ]; then
+    api_mb_search_artist "$FZF_QUERY" |
+      $JQ '.artists[] | [
+    .id,
+    .type,
+    .name,
+    .disambiguation,
+    .["life-span"].begin,
+    .["life-span"].end
+    ] | join("\t")' |
+      awk \
+        -F "\t" \
+        -v file_local_artists="${LOCALDATA_ARTISTS:-}" \
+        -v format_person="$AV_PERSON" \
+        -v format_group="$AV_GROUP" \
+        -v format_disambiguation="$AV_DISAMBIGUATION" \
+        -v format_local="$FORMAT_LOCAL" \
+        "$AWK_ARTISTS" >"$RESULTS" ||
+      true
+  else
+    api_mb_search_releasegroup "$FZF_QUERY" |
+      $JQ '."release-groups"[] | [ 
+    .id,
+    ."primary-type",
+    (."secondary-types" // []|join(";")),
+    ."first-release-date",
+    .title,
+    (."artist-credit" | map(([.name, .joinphrase]|join(""))) | join(""))
+    ] | join("\t")' |
+      awk \
+        -F "\t" \
+        -v file_local_releasegroups="${LOCALDATA_RELEASEGROUPS:-}" \
+        -v format_release="$RGV_RELEASE" \
+        -v format_release_w_artist="$RGV_RELEASE_W_ARTIST" \
+        -v format_year="$RGV_YEAR" \
+        -v format_album="$FORMAT_TYPE_ALBUM" \
+        -v format_single="$FORMAT_TYPE_SINGLE" \
+        -v format_ep="$FORMAT_TYPE_EP" \
+        -v format_broadcast="$FORMAT_TYPE_BROADCAST" \
+        -v format_other="$FORMAT_TYPE_OTHER" \
+        -v format_has_secondary="$FORMAT_TYPE_HAS_SECONDARY" \
+        -v format_secondary="$FORMAT_TYPE_SECONDARY" \
+        -v format_compilation="$FORMAT_TYPE_SECONDARY_COMPILATION" \
+        -v format_soundtrack="$FORMAT_TYPE_SECONDARY_SOUNDTRACK" \
+        -v format_spokenword="$FORMAT_TYPE_SECONDARY_SPOKENWORD" \
+        -v format_interview="$FORMAT_TYPE_SECONDARY_INTERVIEW" \
+        -v format_audiobook="$FORMAT_TYPE_SECONDARY_AUDIOBOOK" \
+        -v format_audiodrama="$FORMAT_TYPE_SECONDARY_AUDIODRAMA" \
+        -v format_live="$FORMAT_TYPE_SECONDARY_LIVE" \
+        -v format_remix="$FORMAT_TYPE_SECONDARY_REMIX" \
+        -v format_djmix="$FORMAT_TYPE_SECONDARY_DJMIX" \
+        -v format_mixtape="$FORMAT_TYPE_SECONDARY_MIXTAPE" \
+        -v format_demo="$FORMAT_TYPE_SECONDARY_DEMO" \
+        -v format_fieldrec="$FORMAT_TYPE_SECONDARY_FIELDREC" \
+        -v format_local="$FORMAT_LOCAL" \
+        "$AWK_RELEASEGROUPS" |
+      cut -d "$(printf '\t')" -f 2- >"$RESULTS" ||
+      true
+  fi
+  # Process ends now: Display and quit
+  rm -f "$LOCKFILE" "$PIDFILE"
+}

src/sh/mpv.sh

@@ -1,61 +1,104 @@
+# Interface to the mpv music player. This interface communicates to an mpv
+# instance through the socket `MPV_SOCKET`.
+
+# Internal helper method to send a command without arguments to mpv
+#
+# @argument $1: command
 __mpv_command() {
   printf "{ \"command\": [\"%s\"] }\n" "$1" | $SOCAT - "$MPV_SOCKET"
 }
 
+# Internal helper method to send a command with a single argument to mpv
+#
+# @argument $1: command
+# @argument $2: argument
 __mpv_command_with_arg() {
   printf "{ \"command\": [\"%s\", \"%s\"] }\n" "$1" "$2" | $SOCAT - "$MPV_SOCKET"
 }
 
+# Internal helper method to send a command with two arguments to mpv
+#
+# @argument $1: command
+# @argument $2: argument 1
+# @argument $3: argument 2
 __mpv_command_with_args2() {
   printf "{ \"command\": [\"%s\", \"%s\", \"%s\"] }\n" "$1" "$2" "$3" | $SOCAT - "$MPV_SOCKET"
 }
 
+# Internal helper method to resolve mpv variables
+#
+# @argument $1: mpv expression
 __mpv_get() {
   __mpv_command_with_arg "expand-text" "$1" | $JQ '.data'
 }
 
+# Get the total number of tracks in the playlist
 mpv_playlist_count() {
   __mpv_get '${playlist-count}'
 }
 
+# Get the position of the current track in the playlist (0 based)
 mpv_playlist_position() {
   __mpv_get '${playlist-pos}'
 }
 
+# Move track on playlist
+#
+# @argument $1: track index 1
+# @argument $2: track index 2
+#
+# Moves the track at the first index to the position of the track of the second
+# index. Also here, indices are 0 based.
 mpv_playlist_move() {
   __mpv_command_with_args2 "playlist-move" "$1" "$2" >>/tmp/foo
 }
 
+# Remove all tracks from the playlist
 mpv_playlist_clear() {
   __mpv_command "playlist-clear"
 }
 
+# Randomly shuffle the order of the tracks in the playlist
 mpv_playlist_shuffle() {
   __mpv_command "playlist-shuffle"
 }
 
+# Revert a previously shuffle command
+#
+# This method works only for a first shuffle.
 mpv_playlist_unshuffle() {
   __mpv_command "playlist-unshuffle"
 }
 
+# Quit the mpv instance bound to the socket `MPV_SOCKET`
 mpv_quit() {
   __mpv_command "quit"
 }
 
+# Start an mpv instance and bind it to the socket `MPV_SOCKET`
 mpv_start() {
   MPV_SOCKET="$(mktemp --suffix=.sock)"
   trap 'mpv_quit >/dev/null; rm -f "$MPV_SOCKET"' EXIT INT
   $MPV --no-config --no-terminal --input-ipc-server="$MPV_SOCKET" --idle --no-osc --no-input-default-bindings &
 }
 
+# Play the track at the specified index in the playlist
+#
+# @argument $1: index (0 based)
 mpv_play_index() {
   __mpv_command_with_arg "playlist-play-index" "$1"
 }
 
+# Remove the track at the specified index from the playlist
+#
+# @argument $1: index (0 based)
 mpv_rm_index() {
   __mpv_command_with_arg "playlist-remove" "$1"
 }
 
+# Load the playlist with the specified list, and start playing
+#
+# This method reads from stdin a playlist file, e.g., a .m3u file.
 mpv_play_list() {
   t=$(mktemp)
   cat >"$t"
@@ -63,6 +106,9 @@ mpv_play_list() {
   rm -f "$t"
 }
 
+# Append the playlist with the specified list, and start playing
+#
+# This method reads from stdin a playlist file, e.g., a .m3u file.
 mpv_queue_list() {
   t=$(mktemp)
   cat >"$t"
@@ -70,6 +116,10 @@ mpv_queue_list() {
   rm -f "$t"
 }
 
+# Insert the playlist with the specified list as the next item, and start
+# playing
+#
+# This method reads from stdin a playlist file, e.g., a .m3u file.
 mpv_queue_next_list() {
   t=$(mktemp)
   cat >"$t"
@@ -86,22 +136,27 @@ mpv_queue_next_list() {
   done
 }
 
+# Play next track on playlist
 mpv_next() {
   __mpv_command "playlist-next"
 }
 
+# Play previous track on playlist
 mpv_prev() {
   __mpv_command "playlist-prev"
 }
 
+# Seek forward by 10 seconds
 mpv_seek_forward() {
   __mpv_command_with_arg "seek" "10"
 }
 
+# Seek backward by 10 seconds
 mpv_seek_backward() {
   __mpv_command_with_arg "seek" "-10"
 }
 
+# Pause if mpv plays, and play if it is paused
 mpv_toggle_pause() {
   __mpv_command_with_arg "cycle" "pause"
 }

src/sh/playback.sh

@@ -21,6 +21,7 @@ if [ ! "${PLAYBACK_LOADED:-}" ]; then
 fi
 
 # Obtain playback command from key press
+#
 # @argument $1: key
 __playback_cmd_from_key() {
   key=$1
@@ -43,9 +44,10 @@ __playback_cmd_from_key() {
 }
 
 # Generate playlist from MB release ID and path to decoration
-# @argument $1: MusicBrainz Release ID
+#
+# @argument $1: MusicBrainz release ID
 # @argument $2: Path to decoration file
-# @argument $3: MusicBrainz Track ID to select (optional)
+# @argument $3: MusicBrainz track ID to select (optional)
 __generate_playlist() {
   printf "#EXTM3U\n"
   dir="$(dirname "$2")"

src/sh/playlist.sh

@@ -1,3 +1,7 @@
+# Playlist manipulation
+#
+# This files provides an interface to manipulate the playlist. The available
+# commands are defined in the following variables.
 if [ ! "${PLAYLIST_LOADED:-}" ]; then
   PLAYLIST_CMD_REMOVE="rm"
   PLAYLIST_CMD_UP="up"
@@ -26,14 +30,14 @@ playlist() {
   "$PLAYLIST_CMD_DOWN") mpv_playlist_move $((FZF_POS - 0)) $((FZF_POS - 1)) ;;
   "$PLAYLIST_CMD_CLEAR") mpv_playlist_clear ;;
   "$PLAYLIST_CMD_CLEAR_ABOVE")
-    for i in $(seq "$FZF_POS"); do
+    for _ in $(seq "$FZF_POS"); do
       mpv_rm_index 0
     done
     ;;
   "$PLAYLIST_CMD_CLEAR_BELOW")
     cnt=$(mpv_playlist_count)
     rem=$((cnt - FZF_POS + 1))
-    for i in $(seq "$rem"); do
+    for _ in $(seq "$rem"); do
       mpv_rm_index $((FZF_POS - 1))
     done
     ;;

src/sh/preview.sh

@@ -1,10 +1,19 @@
+# Preview methods
+#
+# For now, only artist previews are supported.
+
+# This internal method reshapes the text to be shown in the preview. This
+# creates a border on both horizontal ends.
+#
+# The text is read from stdin.
 __shape() {
   cat | tr -d '\r' | fold -s -w "$((FZF_PREVIEW_COLUMNS - 4))" | awk '{print "  "$0"  "}'
 }
 
 # Print preview of artist
-# @input $1: MusicBrainz Artist ID
+#
-__preview_artist() {
+# @input $1: MusicBrainz artist ID
+preview_artist() {
   desc=$(mb_artist_enwikipedia "$1" | $JQ '.extract' | __shape)
   [ "$desc" ] || desc=$(mb_artist_discogs "$1" | $JQ '.profile' | sed 's/\[a=\([^]]*\)\]/\1/g' | __shape)
   if [ "$(mb_artist "$1" | $JQ '.type')" = "Person" ]; then

src/sh/query.sh

@@ -25,11 +25,16 @@
 # - q_single: Release group is of type single
 # - q_official: Release is official
 
+# Clean a filter string
+#
+# This method reads from stdin a string and removes all colors and escapes
+# white spaces.
 __clean_filter() {
   cat | sed "s/${ESC}\[[0-9;]*[mK]//g" | sed "s/ /\\\ /g"
 }
 
 # Determine preset query
+#
 # @argument $1: Current view
 # @argument $2: Key pressed (optional)
 #

src/sh/tools.sh

@@ -1,3 +1,13 @@
+# Load the tools required for this application. The tools are preset with
+# default command-line arguments.
+#
+# List of tools:
+# - fzf:   in order to display, search, and navigate lists
+# - curl:  for API access
+# - jq:    to parse json files
+# - mpv:   music player
+# - socat: to communicate with the socket mpv is bound to
+# - xsel:  to copy content to the clipboard (not necessary)
 if [ ! "${TOOLS_LOADED:-}" ]; then
   if command -v "fzf" >/dev/null; then
     FZF="fzf --black --ansi --cycle --tiebreak=chunk,index"