fuzic

This application allows for a keyboard-controlled maneuvering of your music library and the MusicBrainz database. All metadata is fetched from the MusicBrainz database without tagging your audio files. Effectively, your local library becomes "embedded" in MusicBrainz. You can control playback while browsing the vast world of music releases.

🎞️ Screenshot

🛠️ Requirements and Installation

Requirements

This is an almost¹ POSIX-compliant shell script with inline awk elements (GNU flavored, we couldn't resist) that makes calls to:

the command-line fuzzy finder fzf,
the command-line data transferrer curl,
the command-line JSON processor jq,
the command-line media player mpv, and
the command-line multipurpose relay socat.

The following may improve your experience:

the command-line multimedia prober ffprobe (optional, for automatic release detection),
the command-line clipboard xsel (optional, for yanking urls),
Noto fonts (optional, for emojis in your terminal).

Installation

Run ./scripts/build.sh, then copy fuzic to your preferred location, e.g., ~/.local/bin, and make it executable.

🧩 Configuration

Although no configuration is needed, this application may be customized using environment variables. If the file $XDG_CONFIG_HOME/fuzic/config (defaults to $HOME/.config/fuzic/config) exists, then it will be sourced. You may also specify an alternative location of the configuration file with the environment variable CONFIGFILE.

The appearance of the application is controlled using the environment variables defined in src/sh/theme.sh. The directory share/theme contains example themes. You may execute CONFIGFILE=share/theme/plain.sh fuzic to launch fuzic using an emojiless and colorless theme.

Custom filters can be defined using the environment variables from src/sh/filter.sh. For instance, when you launch F_2_LIST_ARTISTS="jazz" fuzic, then the artist list can be queried for the word jazz by pressing alt-2.

Also the key bindings can be reconfigured to your liking. For that, adjust the environment variables defined in src/sh/keys.sh.

Finally, you can sort the artists according to their sort name by specifying SORT_ARTIST_DEFAULT=sort-artist-sortname, and the switch to alphabetical release-group sorting via SORT_RG_DEFAULT=sort-rg-title.

▶️ Usage

For a quick start, run the application and hit alt-? to display the available key-bindings. You may also open the application in one of the following predefined modes:

Usage: fuzic [OPTION]

GENERAL OPTIONS:
  --help                        Show this help and exit
  --artists                     Default options, list artists of local music
  --albums                      List albums of local music
  --search-artist               Search artist on MusicBrainz
  --search-album                Search album on MusicBrainz
  --artist <mbid>               List release groups of given artist <mbid>
  --releasegroup <mbid>         List releases in given release group <mbid>
  --release <mbid>              Show release given by <mbid>

MANAGE LOCAL MUSIC:
  --decorate <path>             Decorate directory containing a tagged release
  --decorate-as <path> <mbid>   Decorate directory as the relase <mbid>
  --reload-database <path>      Populate database with decorated local music from <path>

🗄️ Local Music Library

Instead of reading the tags from audio files, this application uses decorations. The decoration of a folder is a JSON files that stores the relevant MusicBrainz IDs of the release the folder corresponds to. This assumes that complete releases are stored within separate folders. The application then fetches the relevant metadata, which is displayed to the user. Folders can be decorated using fuzic --decorate <path> or fuzic --decorate-as <path> <mbid> commands. The first version may be used on tagged files (using, e.g., MusicBrainz Picard). With this command, the folder gets decorated with the relevant MusicBrainz IDs are extracted from the files. The latter version does not require the files to be tagged. Instead, it decorates the files found in that folder as the release given by the MusicBrainz Release ID <mbid>.

After decorating your folders, you may run fuzic --reload-database <path> to build your music library. This command searches the path specified for decorated folders. Once the local music library is built, it will display automatically when fuzic is launched.

⌨️ Basic Keys

As mentioned above, you may hit alt-? anytime to display the possible keys. Note that fuzic allows for two modes: normal mode and insert mode. Similar to vim, keys pressed in the normal mode do not directly write to the input field, but are instead bound to other actions. For instance, the keys j and k can be used to navigate the list down and up. In the insert mode, triggered using i, a, or /, the keys directly modify the input field.

Some central keys are <enter> to start playback of the selected entry, <space> to pause playback, and ctrl-p to open the currently loaded playlist.

🧭 Planned Features

The following features are planned:

offline mode
saving and loading playlists
cover art and artist images
lyrics support
showing current position in track
hooks when played track changes

🌐 Information Sources

Main metadata is fetched from the MusicBrainz database. This application also access wikidata, wikipedia, and discogs. In the future, more sources may be added.

License

This project is licensed under the MIT License.

It is written in POSIX style, but we make use of zero terminated strings. ↩︎