132 lines
6.7 KiB
Markdown
132 lines
6.7 KiB
Markdown
A terminal-based music browser and player.
|
|
|
|
🔍 Key Features
|
|
---------------
|
|
- [Fuzzily](https://github.com/junegunn/fzf) browse your music library
|
|
- Treat your local library as part of the global [MusicBrainz universe](https://musicbrainz.org)
|
|
- Search the MusicBrainz database and discover music artists, and releases
|
|
- Handle metadata without touching your audio files
|
|
- Fast and Hackable application with [vim](https://www.vim.org)-like keybindings
|
|
|
|
🎧 Description and Use Case
|
|
---------------------------
|
|
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[^1] POSIX-compliant shell script with inline `awk` elements (GNU flavored, we couldn't resist) that makes calls to:
|
|
- the command-line fuzzy finder [fzf](https://junegunn.github.io/fzf/),
|
|
- the command-line data transferrer [curl](https://curl.se),
|
|
- the command-line JSON processor [jq](https://jqlang.org),
|
|
- the command-line media player [mpv](https://mpv.io), and
|
|
- the command-line multipurpose relay [socat](http://www.dest-unreach.org/socat/).
|
|
|
|
[^1]: It is written in POSIX style, but we make use of zero terminated strings.
|
|
|
|
The following may improve your experience:
|
|
- the command-line multimedia prober [ffprobe](https://ffmpeg.org/ffprobe.html) _(optional, for automatic release detection)_,
|
|
- the command-line clipboard [xsel](http://www.kfish.org/software/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](https://musicbrainz.org/doc/Style/Artist/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](https://picard.musicbrainz.org/)).
|
|
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](https://musicbrainz.org/doc/MusicBrainz_Identifier) `<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](https://wikidata.org), [wikipedia](https://en.wikipedia.org), and [discogs](https://www.discogs.com).
|
|
In the future, more sources may be added.
|
|
|
|
License
|
|
-------
|
|
This project is licensed under the [MIT License](./LICENSE).
|