Metadata Enhanced Collection Oriented Music Player (MECOMP)

<!-- markdownlint-disable MD033 -->

(name subject to change)

Introduction

MECOMP is a local music player that it is designed to solve a very specific problem:

I have a large collection of music, organizing my music by artist and album is not enough, I want to be able to organize my music by other criteria, such as genre, mood, etc. Typically, I would have to create a playlist for each of these criteria, but that is tedious and time consuming. I want to have automatically curated playlists of similar songs (analogous to genres), dynamically updated playlists of songs that match a certain criteria (basically filters), and be able to create queues of songs that are similar to the current song (think Pandora). There are some services that let you do most of these, like Spotify, but I want to be able to do this with my local music collection and not have to rely on a third party service.

Installation

<details> <summary>Aside: Linux Dependencies</summary>

On linux, you will need to have the following packages installed:

libasound2-dev pkg-config wget libavutil-dev libavformat-dev protobuf-compiler

# debian/ubuntu
sudo apt-get install libasound2-dev pkg-config wget libavutil-dev libavformat-dev protobuf-compiler
# Arch (btw)
sudo pacman -S alsa-lib pkg-config wget ffmpeg protobuf

</details>

Compiling from Source

MECOMP is written in rust, so you will need to have the rust toolchain installed, you can find installation instructions here.

then clone the repository and compile the project, we provide an x.sh script that will compile the binaries for you:

git clone https://github.com/AnthonyMichaelTDM/mecomp.git
cd mecomp
./x.sh b # or `cargo build --release --bins` if you don't want to use the script

this will compile the project and place the binaries in the target/release directory.

Releases

Precompiled binaries for the latest releases can be found on the releases page. Checksums for the binaries are attached to the release notes.

The following platforms are supported:

• macOS (aarch64)
• Linux (x86_64)
• Windows (x86_64)

You can download the appropriate binary for your platform and extract it to a directory of your choice, use the provided installers, or use cargo binstall as described below:

cargo install cargo-binstall
cargo binstall mecomp-daemon mecomp-cli mecomp-tui

Crates.io

MECOMP is published on crates.io, you can install the binaries by running:

cargo install mecomp-daemon mecomp-cli mecomp-tui

Usage

Note: the following commands assume the MECOMP binaries are either in your PATH or in the current directory.

If you compiled the binaries from source, you can cd into the target/release directory and run the commands from there.

MECOMP is composed of a daemon and several clients that communicate with the daemon, the daemon is the core of the application and handles all the backend logic and state-management necessary for the application to function, the clients are simply frontends to this server.

Before you can use MECOMP, you will need to start the daemon, you can do this by running the daemon binary:

./mecomp-daemon

this will start the daemon, which will listen for RPC requests on localhost:6600 by default (the same port that MPD uses).

Once the daemon starts, it will create a configuration file in the "mecomp" directory in your user's configuration directory:

• C:\Users\username\AppData\Roaming\mecomp on windows
• $HOME/Library/Application Support/mecomp on mac
• $XDG_CONFIG_HOME/mecomp on linux

You can use this file to configure things such as the root directory of your music collection, the port the daemon listens on, etc.

Once you have things configured to your liking, you'll have to restart the daemon for the changes to take effect.

Then, you'll have to tell the daemon to start scanning and analysing your music collection, you can do this (in a separate terminal) by running:

# Tell the daemon to start scanning your music collection
./mecomp-cli library rescan
# before moving on, wait for the daemon to finish scanning your music collection
# it will tell you in the logs when it's done, but you can also check the status by running
./mecomp-cli status rescan

# once the daemon has finished scanning your music collection, you can tell it to start analysing your music collection
./mecomp-cli library analyze
# again, wait for the daemon to finish analysing your music collection, it will tell you in the logs when it's done,
# and you can check the status by running
./mecomp-cli status analyze

# once the daemon has finished analysing your music collection, you can tell it to start clustering your music collection
./mecomp-cli library recluster
# again, wait for the daemon to finish clustering your music collection, it will tell you in the logs when it's done,
# and you can check the status by running
./mecomp-cli status recluster

Each of these commands will take some time to complete.

Once the daemon is up and running and has finished scanning, analysing, and clustering your music collection, you can use the clients to interact with the daemon, the current most "user-friendly" client is the TUI, you can start the TUI by running:

./mecomp-tui

this will start the TUI in your console, which will allow you to interact with the daemon.

Adding Music

To add music to the app, simply put the music files into one of the directories configured in the daemon's configuration file, then tell the daemon to rescan your music collection. By default, this includes your users Music directory, but you can add more directories by editing the configuration file.

Aside: How do I get music?

You can get music from a variety of sources, such as:

• ripping CDs
• purchasing/downloading music from an artist's website
• purchasing/downloading music from bandcamp, soundcloud, etc.
• downloading music from youtube
• etc.

For example, you can use a tool like yt-dlp to download music from youtube music

# example, downloads a playlist from YouTube Music, and converts it to mp3
yt-dlp --extract-audio --audio-format mp3 --yes-playlist --embed-thumbnail --embed-metadata --concurrent-fragments 4 -o '%(title)s.%(ext)s' <playlist-url>

(replace <playlist-url> with the url of the playlist you want to download)

you can then use an audio tagger such as MusicBrainz Picard to tag the music files with missing metadata.

Shell Completions

All the MECOMP binaries have COMPLETE=$SHELL <bin> integration thanks to clap_complete. To use it, you can run (or add to your .zshrc / .bashrc) the following:

source <(COMPLETE=bash mecomp-cli)

(repeat for mecomp-daemon, mecomp-tui, etc.)

Architecture

MECOMP is designed to be modular and extensible, and is composed of a daemon (which is the core of the application), and several clients that communicate with the daemon.

MECOMP-Daemon

MECOMP-Daemon is a long-running RPC server that is the core of the application, it handles all the backend logic and state-management necessary for the application to function. the MECOMP clients are simply frontends to this server. It is written in rust and uses gRPC (implemented with the tonic library) for inter-process communication via RPC.

Clients

MECOMP-CLI

MECOMP-CLI is a command line interface for MECOMP, it provides a simple way to interact with the daemon.

MECOMP-MPRIS

MECOMP-MPRIS is a MPRIS interface for MECOMP, it allows MPRIS compatible clients to interact with the daemon.

Currently, only the Player interface is implemented, but the TrackList and Playlists interfaces are planned for the future.

MECOMP-TUI

MECOMP-TUI is a terminal user interface for MECOMP, it provides a more user friendly way to interact with the daemon, but still in a terminal.

MECOMP-GUI

MECOMP-GUI is a graphical user interface for MECOMP, it provides a more user friendly way to interact with the daemon.

the GUI is not currently implemented, but is planned for the future.

Have a question or need help?

If you have a question or need help, feel free ask in the discussions section of the repository.

If you encounter a bug or have a feature request, please open an issue in the issues section of the repository.

Note about bugs: if you encounter a bug, please provide as much information as possible, including the steps to reproduce the bug, the expected behavior, the actual behavior, and any error messages you see, without this information it will be very difficult to diagnose and fix the bug.

Features