fuzic/README.md

🎧 Description and Use Case

This application allows for a keyboard-controlled maneuvering of your music library and the MusicBrainz database. Your local library becomes "embedded" in MusicBrainz, and all metadata remains up-to-date without the need of tagging your files. Control playback from your terminal while browsing the vast world of music releases.

🔍 Key Features

• Fuzzily browse your music library
• Treat your local library as part of the MusicBrainz universe
• Search the MusicBrainz database and discover music artists and releases
• Handle metadata without touching your audio files
• Fast and hackable application with vim-like keybindings
• Save and load playlists
• Lyrics support

🎞️ Screenshot

Search Artist on MusicBrainz

The MusicBrainz database is automatically searched after entering a query. In the screenshot below, the emoji 🔆 indicates that some tracks of Mc Solaar are available in the local music library. They are played by hitting <enter>.

Browse Local Music Library

Here, we fuzzily search an album of Daft Punk. The LP Random Access Memories can be appended to the playlist by pressing ctrl-alt-m. Alternatively, you may switch back to normal mode (esc) and then hit ;.

Playlist Control

You can easily control playback and edit the playlist in the playlist view.

🛠️ 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>
  --playlists                   List stored playlists and exit
  --load-playlist <playlist>    Load specified playlist

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 file 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 previously tagged files (using, e.g., MusicBrainz Picard). With this command, the folder gets decorated with the MusicBrainz IDs 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.

Workflow Example

$ fuzic --decorate ~/Music/Daft\ Punk/Random\ Access\ Memories 
Info: Decorating /home/amin/Music/Daft Punk/Random Access Memories as release 5000a285-b67e-4cfc-b54b-2b98f1810d2e
$ fuzic --decorate-as ~/Music/Mc\ Solaar/Prose\ Combat 69e5cf67-7cea-4fe8-9129-9779f0a93d69
Info: Decorating /home/amin/Music/Mc Solaar/Prose Combat as the release Prose Combat by MC Solaar
Info: We discovered the following association:
Track 'Aubade'                         File './01 Aubade.m4a'
Track 'Obsolète'                       File './02 Obsolète.m4a'
Track 'Nouveau western'                File './03 Nouveau western.m4a'
Track 'À la claire fontaine'           File './04 À la claire fontaine.m4a'
Track 'Superstarr'                     File './05 Superstarr.m4a'
Track 'La Concubine de l’hémoglobine'  File './06 La Concubine de l’hémoglobine.m4a'
Track 'Dévotion'                       File './07 Dévotion.m4a'
Track 'Temps mort'                     File './08 Temps mort.m4a'
Track 'L’NMIACCd’HTCK72KPDP'           File './09 L’NMIACCd’HTCK72KPDP.m4a'
Track 'Séquelles'                      File './10 Séquelles.m4a'
Track 'Dieu ait son âme'               File './11 Dieu ait son âme.m4a'
Track 'À dix de mes disciples'         File './12 À dix de mes disciples.m4a'
Track 'La fin justifie les moyens'     File './13 La fin justifie les moyens.m4a'
Track 'Relations humaines'             File './14 Relations humaines.m4a'
Track 'Prose combat'                   File './15 Prose combat.m4a'
Info: Are the track correctly associated to the audio files? (yes/no) yes
$ fuzic --reload-database ~/Music
Info: Reloading information of local music directory /home/amin/Music
Info: Fetching missing releases
Info: 1/2 (5000a285-b67e-4cfc-b54b-2b98f1810d2e: Random Access Memories)
Info: 2/2 (69e5cf67-7cea-4fe8-9129-9779f0a93d69: Prose Combat)
Info: Fetching missing release groups
Info: 1/2 (aa997ea0-2936-40bd-884d-3af8a0e064dc: Random Access Memories)
Info: 2/2 (b199910b-0f90-3c88-b523-d6852b7612d3: Prose Combat)
Info: Fetching missing artists
Info: 1/2 (056e4f3e-d505-4dad-8ec1-d04f521cbb56: Daft Punk)
Info: 2/2 (bbbd2644-b4cb-4bb5-a442-315310f68a0b: MC Solaar)
Info: Done

⌨️ 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.

📝 Playlist Store

Playlists can be saved, loaded and shared. To save a playlist, simply press ctrl-s when viewing your playlist. To load a playlist, open the playlist store using ctrl-o while viewing your playlist. Alternatively, you may start fuzic using the command-line parameters fuzic --load-playlist <playlist>. Under the hood, a playlist is not more than a sequence of MusicBrainz IDs. This means that fuzic users may share their playlists irrespective of the audio file locations and formats. Possibly even more importantly, this means that you can preserve your playlist even if you reorganize your local music library: You can safely share your playlists with your future self.

Playlists are stored under XDG_DATA_HOME/fuzic/playlists, which defaults to ~/.local/share/fuzic/playlists. You may also define the playlist directory using the PLAYLIST_DIRECTORY environment variable. In share/playlists you find example playlists. Thus, the command PLAYLIST_DIRECTORY=share/playlists fuzic launches this application with access to these example playlists.

📜 Lyrics

By using the key L (normal mode), the lyrics of the selected track are displayed. The lyrics are taken from (in that order)

1. the lyrics stored using fuzic, or
2. from the .lrc file with the same name as the audio file, or
3. from the audio-file tags (requires ffprobe), or
4. from a custom script.

To specify the custom script, you can set the LYRICS_FETCH_CUSTOM environment variable to point to an executable. The executable reads a JSON string on the standard input, and is supposed to print the lyrics (see share/lyrics/example.sh).

You may also skip the first three sources and directly make a call to your custom script by using the key Y (normal mode).

The key alt-L opens the lyrics in a new window using the EDITOR. This requires one of the following terminal emulators (kitty, x-terminal-emulator, gnome-terminal, xterm). If you use another terminal emulator, you may specify the environment variable EXTERNALEDIT to hold the string such that

$ExTERNALEDIT "$file"

spawns a text editor with $file loaded inside a terminal emulator.

🧭 Planned Features

The following features are planned:

• cover art and artist images
• genre support
• MusicBrainz collections and favorites

🌐 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.

---

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