From 6bfb7f03990d60170578aacdd84a07b6e5d75f21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=84min=20Baumeler?= Date: Fri, 10 Oct 2025 10:50:16 +0200 Subject: [PATCH] improved readme --- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 57 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 4cb3061..8376883 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ +🎧 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](https://github.com/junegunn/fzf) browse your music library @@ -6,23 +12,22 @@ - 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 ------------- ### 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 ``. ![MusicBrainz artist search](//screenshots/search.png) ### 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 `;`. ![Browse library](./screenshots/browse.png) ### Playlist Control +You can easily control playback and edit the playlist in the playlist view. ![Playlist](./screenshots/playlist.png) 🛠️ Requirements and Installation @@ -47,7 +52,7 @@ Run `./scripts/build.sh`, then copy `fuzic` to your preferred location, e.g., `~ 🧩 Configuration ----------------- -Although no configuration is needed, this application may be customized using environment variables. +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`. @@ -58,10 +63,10 @@ You may execute `CONFIGFILE=share/theme/plain.sh fuzic` to launch `fuzic` using 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. +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`, +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`. @@ -92,11 +97,11 @@ MANAGE LOCAL MUSIC: 🗄️ 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. +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 ` or `fuzic --decorate-as ` commands. -The first version may be used on tagged files (using, e.g., [MusicBrainz Picard](https://picard.musicbrainz.org/)). +The first version may be used on previously 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) ``. @@ -105,6 +110,43 @@ After decorating your folders, you may run `fuzic --reload-database ` to b 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 associatoin: +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. @@ -118,12 +160,13 @@ Some central keys are `` to start playback of the selected entry, `