Installation & basic local configuration

Euphonica is not a self-contained music player. It is specifically a client for Music Player Daemon, which acts as the "playback engine" as well as the library manager. In order to use Euphonica, you must have an MPD server up and running first.

This page provides a simple step-by-step guide to a simple setup, enabling you to use Euphonica to play back local music files like a typical music player. More advanced multi-machine setups might have their own guide in the future.

Prerequisites

• Ensure your system is reasonably up-to-date, especially if you plan on installing Euphonica without Flatpak sandboxing.
• Use PipeWire instead of PulseAudio for your local audio stack. This is already the case for most modern distros.
• Check your music library for potential incompatibilities:
  • Tracks from the same release should be placed in their own folder, without tracks from other releases. More specifically, all tracks in the same folder should have the same album tag. This ensures file-based album arts work correctly.
  • Using album art files is preferred to having covers embedded in files. These files must be named cover.png, cover.jpg, or cover.webp, as required by MPD itself.
    • This preference stems from efficiency reasons. Firstly, such an album art will be stored exactly once on disk, saving you some disk space compared to embedding one copy in each track file. Secondly, Euphonica always prefers these files to embedded covers whenever possible, as it would only need to download one file for each album tag. Optimisations have also been put in place to reduce duplicated downloads on Euphonica's side, but simply using file-based album arts is still recommended.
  • Tag your tracks as completely as you can. The most important tags are title, album, artist, and albumartist. You are encouraged to tag your tracks with information from MusicBrainz and provide MusicBrainz IDs under the musicbrainz_albumid, musicbrainz_artistid, and musicbrainz_trackid tags. Euphonica can take advantage of these MusicBrainz IDs to look up metadata with much greater accuracy and hit rate than using natural-language titles and names, which might be subject to varying punctuations and spellings.
    • Tip: use Beets to automate tagging large libraries. Euphonica is tested against Beets-tagged libraries. If you already have your own tags and wish to keep them, be sure to back them up first.

Install & configure MPD

Installation

MPD is in the official repositories of most popular Linux distributions, so you can install it using your system's package manager.

Ubuntu / Debian:

sudo apt update
sudo apt install mpd

Fedora:

sudo dnf install mpd

Arch Linux:

sudo pacman -S mpd

Once installed, the MPD service won't be active by default on most modern systems. You'll set that up later, after the configuration is complete.

Once MPD is installed, you need to configure it to point to your music library and specify how it should handle audio output. The configuration is done in the mpd.conf file.

Configuration

MPD can't work right away as it has to be adapted to the specifics of your hardware and library. This is done via the mpd.conf file.

Detailed instructions are provided in MPD's own documentation. We provide an abbreviated version adapted to Euphonica below.

Setting MPD up as a system-wide service requires root permissions and provides zero benefit to Euphonica. It is therefore highly recommended to simply set MPD up as a user service. This means you should create an empty text file named mpd.conf at $XDG_CONFIG_HOME/mpd/mpd.conf (usually corresponding to ~/.config/mpd/mpd.conf).

Use the following commands to create the necessary folders and the config file:

# Create the configuration folder in case you don't have one yet
mkdir -p ~/.config/mpd
# Create an empty configuration file in that folder
touch ~/.config/mpd/mpd.conf
# MPD also needs a place to store its database files. A common location would be a `.mpd` folder in your ~. The dot marks it as hidden so as not to clutter your home folder.
mkdir -p ~/.mpd

Open your mpd.conf with your favourite text editor and follow the next steps.

Pointing MPD to your library

First, we must tell MPD where to find your music files.

Open the configuration file ~/.config/mpd/mpd.conf in your favourite text editor. Let's assume your music library is stored in ~/Music. Add the following:

music_directory         "~/Music"

Note: This path must be readable by the user running the MPD service. As we'll run MPD under our own user, this shouldn't be a problem.

The music files need not be on the same machine as the one running MPD and Euphonica. One can also point MPD to a library stored elsewhere over a network. Please refer to the satelite setup guide for more information.

Database files

Tell MPD where to store its internal database, state, and log files.

db_file                 "~/.mpd/database"
log_file                "~/.mpd/log"
state_file              "~/.mpd/state"
pid_file                "~/.mpd/pid"

Note how they are all in the ~/.mpd folder we have created earlier.

Setting up audio outputs

The audio_output section defines where audio will be played. Here we'll simply make MPD play audio directly through your machine.

There are many options for local audio playback (PulseAudio, PipeWire, JACK, directly to ALSA, etc). However, Euphonica's internal visualiser only supports PipeWire (and FIFO, but that's something for later). As such, we'll set up a PipeWire output.

audio_output {
    type            "pipewire"
    name            "PipeWire"   # This will be the displayed name in Euphonica's UI.
}

Optional features (recommended)

While not strictly required, adding these to your config file will enable additional capabilities in Euphonica.

• Sticker database: This enables the storage of arbitrary "stickers" without requiring write access to your library. Euphonica uses this to enable album-level rating stars.

  sticker_file            "~/.mpd/sticker.db"
  

• Playlists: This allows MPD to save and manage playlists. Euphonica comes with playlist management features, such as saving your current queue as a playlist, queuing & editing existing ones, etc.

  playlist_directory      "~/.mpd/playlists"
  

You can now save your mpd.conf file and return to the terminal.

Starting MPD

MPD is a daemon, which means it's designed to run silently in the background. It waits for commands from a client (like Euphonica) to manage & play your music.

The best way to run MPD is as a user service with systemd. This ensures MPD starts and stops with your user session without requiring any manual action.

systemctl --user start mpd

To ensure MPD starts automatically every time you log in, enable the service.

systemctl --user enable mpd

Now check if MPD is up and running:

systemctl --user status mpd

This will show you the status of the daemon. Look for "Active: active (running)".

Install & configure Euphonica

TODO

Connecting to MPD

TODO

Spectrum visualiser

TODO