GitHub - doctorfree/MusicPlayerPlus: Featureful ncurses based MPD client inspired by ncmpc with integration for Beets, spectrum visualization,Bandcamp/Soundcloud, asciimatics, cantata, and more

MusicPlayerPlus is a character-based console and terminal window music player

plus Beets media library management with preconfigured plugins
plus Character-based spectrum visualizer mppcava
plus Music Player Daemon and ALSA configuration management
plus Mopidy Music Server with preconfigured extensions
plus Navidrome Music Server/Streamer automated install/config/service
plus Spotify and YouTube Music players
plus Bliss acoustic analysis and song similarity database
plus Essentia acoustic analysis and metadata extraction
plus YAMS MPD Last.fm scrobbler running as a service
plus Media fuzzy finder using fzf
plus Album cover art download
plus Bandcamp collections download
plus Soundcloud favorites download
plus Discogs user collection to markdown generator
plus Automated setup, import and organization, metadata, playlists, ...

Overview
1. Requirements
2. MusicPlayerPlus Commands
Quickstart
1. Quickstart summary
2. Full Tilt Boogie
Installation
Post Installation Configuration
MusicPlayerPlus Services and Clients
Documentation
Removal
Troubleshooting
1. Known issues
Infrared remote control of MPD
Screenshots
Videos
Building MusicPlayerPlus from source
Contributing

Overview

The MusicPlayerPlus project provides integration and extension of several audio packages designed to stream and play music. MusicPlayerPlus interacts with the Music Player Daemon (MPD). Outputs from the MPD streaming audio server are used as MusicPlayerPlus inputs for playback and visualization. MusicPlayerPlus components are used to manage and control MPD and ALSA configuration.

MusicPlayerPlus integrations and extensions are primarily aimed at the character-based terminal user. They enable an easy to use seamlessly integrated control of audio streaming, playing, music library management, and visualization in a lightweight character-based environment.

Audio streaming is provided by the Music Player Daemon (MPD). At the core of MusicPlayerPlus is the mpplus command which acts as a front-end for a variety of terminal and/or tmux sessions.

The mpplus command can be used to invoke:

The lightweight character-based MPD client, mpcplus
One or more terminal emulators running an MPD client and visualizer
A tmux session using the tmux session manager tmuxp
A spectrum visualizer
A download of album cover art for every album in a music library
Conversion of all WAV/M4A format media in a music library to MP3 format media
An import of a music library to the Beets media library manager
A download of lyrics for all songs in the music library without lyrics
Analysis and retrieval of audio-based information for media matching a query
YAMS MPD Last.fm scrobbler activation
Any MPD client the user wishes to run
One of several asciimatics animations optionally accompanied by audio
A fuzzy listing and searching of the audio library using fzf

[Note:] Typical use of mpplus as a music player and spectrum visualizer will invoke a tmux session to display the MPD client, spectrum visualizer, and album cover art all in a single terminal window. MusicPlayerPlus configures tmux with a custom key binding to exit tmux sessions. To exit an mpplus tmux session, the Alt-x key binding can be used.

Integration is provided for:

mpd, the Music Player Daemon
mpcplus, character-based MPD client
beets, media library management system
essentia, acoustic metadata analysis and extraction
mopidy, music server with cool extensions
navidrome, self-hosted music server and streamer
yams, MPD scrobbler for Last.fm
cava, an audio spectrum visualizer
mplayer, a media player
fzf, interactive fuzzy finder
asciimatics - automatically display a variety of character-based animation effects
asciinema - automatically create ascii character-based video clips
tmux, a terminal multiplexer
tmuxp, a tmux session manager
Enhanced key bindings for extended control of terminal windows and tmux sessions
Several terminal emulators
- kitty (the default MusicPlayerPlus terminal emulator)
- cool-retro-term
- gnome-terminal
- tilix

The goal of MusicPlayerPlus is to provide the user with a sophisticated set of complex music library tools that can be integrated and managed in a fairly simple to understand fashion. Also, to make some cool looking powerful stuff happen from the command-line in a character-based environment.

Requirements

MusicPlayerPlus is compiled and packaged for installation on Linux platforms. It has been tested on the following platforms:

Arch Linux
CentOS Linux
Fedora Linux
Raspberry Pi OS
Ubuntu Linux

Installation and initialization require admistrative privilege. The mppinit command, executed after installing MusicPlayerPlus, installs several packages and therefore requires access to the Internet along with administrative privilege (e.g. sudo privilege).

Memory and storage requirements depend upon the size of the music library.

With a moderate sized music library, the Music Player Daemon can exceed a 2GB memory capacity. Therefore, 4GB or more of memory is recommended.

Storage should be sized to adequately host what will likely be a growing music library. Plan ahead and leave your library room to grow. A few hundred Gigabytes of storage might suffice for some music libraries but a Terabyte or more will provide room to grow. Testing is performed on systems with 4GB RAM and 2TB storage using a 600GB music library.

Essentia metadata extraction, Blissify similarity analysis, and transcoding all consume significant CPU resources. Testing has been performed on systems with the following CPU resources:

8 x Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz
2 x Intel(R) Celeron(R) CPU G1840 @ 2.80GHz
4 x ARMv7 Processor rev 3 (v7l)

All of these processors were able to handle significant loads. However, import, metadata extraction, and transcoding are all much quicker on the 8 x Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz system. Although not necessary, these infrequent operations consume much less time on a more powerful CPU.

MusicPlayerPlus Commands

MusicPlayerPlus adds the following commands to your system:

mpplus : Primary user interface, invokes an MPD client, spectrum visualizer, and more
mpcplus : Featureful NCurses MPD client, compiled with spectrum visualizer
mppinit : One-time initializaton of a user's mpcplus configuration
mppcover : Display album cover art for currently playing song
mppdl : Downloads audio tracks from Bandcamp, Soundcloud, or a URL
mpcplus-tmux : Runs mpcplus, a visualizer, and displays album art in a tmux session
mppsplash-tmux : Runs mppsplash, a visualizer, in a tmux session
mppsplash : Fun ascii art screens using ASCIImatics animations. Ascii art commands:
- mppjulia : ASCIImatics animated zoom on a Julia Set
- mppplasma : ASCIImatics animated plasma graphic
- mpprocks : ASCIImatics animated MusicPlayerPlus splash screen
raise_cava : Raises the mppcava spectrum visualizer window
set_term_trans : Sets an xfce4-terminal window's transparency level
fzmp : Browse, search, and manage MPD library using fzf fuzzy finder and mpc MPD client
artist_to_albumartist : Copies the Artist tag to the AlbumArtist tag
create_playlist : Create a new playlist using a Beets query
listyt : List YouTube video titles and urls
bliss-analyze : Acoustic analysis of audio files
blissify : Create MPD playlists using song similarity
essentia_streaming_extractor_music : Analyze and extract acoustic characteristics
mpd-configure : Create an MPD configuration file optimized for bit perfect playback
mpd-monitor : Display info on currently playing MPD song

The bliss-analyze and blissify commands are currently not available on Raspberry Pi installations due to lack of support for that architecture in the ffmpeg library.

[Note:] MusicPlayerPlus functions as a front-end and management system for any MPD/Mopidy/Navidrome client. The default MPD client is mpcplus but any MPD client can be configured by setting MPD_CLIENT in ~/.config/mpprc. While mpcplus is the recommended MPD client, ncmpcpp is also supported with some integration for visualizer data source management. Other MPD clients available for use with MusicPlayerPlus include ncmpc, pms, vimpc, pimpd2, nncmpp, mmtc, and mpq.

Additional detail and info can be found in the MusicPlayerPlus Wiki.

Quickstart

Required setup

Create a music library if you do not already have one
- Default MusicPlayerPlus location for the music library is $HOME/Music
- Recommended structure of the music library is artist/album/songs
Install the latest Arch, Debian, or RPM format installation package from the MusicPlayerPlus Releases page
Run the mppinit command as your normal user
- Searches $HOME/Music and $HOME/music for music library location
- The music library location can be specified with mppinit -l /path/to/library

Optional additional setup steps

For many installations, installing the MusicPlayerPlus package and initializing the user configuration with the mppinit command is all that need be done.

Some common additional setup steps that can be performed include:

Configuring the music library location
Download albums in your Bandcamp collections
Download favorites in your Soundcloud account
Converting WAV/M4A format media files to MP3 format
Importing a music library into the Beets library management system
Downloading album cover art
Downloading additional lyrics
Activation of YAMS scrobbler for Last.fm
Analysis and retrieval of audio-based information for media matching a query

Configure the music library location by editing ~/.config/mpprc and setting MUSIC_DIR to your music library location (default setting is ~/Music). Optionally configure any additional settings in ~/.config/mpprc such as your preferred terminal emulator, Bandcamp username, Soundcloud slug, or more. Any changes to ~/.config/mpprc must be followed by running the command mppinit sync.

[Important Note:] MusicPlayerPlus integrates several services, each of which has its own configuration for the location of the music library. Because of this, MusicPlayerPlus provides its own configuration file ~/.config/mpprc. The MUSIC_DIR setting in that config file is used as the source of truth for the location of the music library. In order to keep all of the services in sync with respect to the music library location, set the location in ~/.config/mpprc and run the command mppinit sync. If the music library is moved to a new location, repeat this procedure.

Download albums in your Bandcamp collections with mppinit bandcamp.

Download favorites in your Soundcloud account with mppinit soundcloud.

Two step post-initialization setup

The following optional post-initialization steps can be performed individually as described below or they can be performed in two steps using mppinit.

Step 1, import the music library into Beets:

mppinit import

The mppinit import command converts any WAV format media to MP3 format and imports the music library into the Beets media library management system.

[Note:] A Beets import can take hours for a large music library. A test import using a music library over 500GB in size, with nearly 4000 artists, 3000 albums, and over 30,000 tracks consumed nearly 12 hours. Import times will vary from system to system and library to library depending on several factors. The above test may provide a ballpark idea of the length of time a Beets library import might take.

When the import is complete

Step 2, retrieve additional metadata:

mppinit metadata

The mppinit metadata command identifies and deletes duplicate tracks, retrieves album genres from Last.fm, downloads album cover art, and (optionally) analyzes and retrieves metadata for all songs in the music library.

[Note:] A Beets metadata retrieval can take hours for a large music library. The MusicPlayerPlus default Beets configuration uses ffmpeg to compute checksums for every track in the library to find duplicates.

An optional audio analysis can be performed during metadata retrieval. MusicPlayerPlus provides several optional methods for acoustic analysis. The method used for acoustic analysis and retrieval can be specified on the command line:

AcousticBrainz metadata retrieval (deprecated)
- mppinit -a metadata
Blissify acoustic analysis of the MPD music library (the default)
- mppinit -b metadata
Essentia acoustic analysis and Beets metadata retrieval (long)
- mppinit -e metadata

If none of the -a, -b, or -e options are specified then acoustic analysis, extraction, and retrieval is performed by Essentia.

The AcousticBrainz service is the fastest method but is being retired in 2023, the service is no longer being updated, and it is often inaccurate.

The Essentia acoustic analysis is the most thorough, adds acoustic metadata to the Beets library management system, and provides the greatest flexibility but at a cost of possibly days of analysis and extraction time. Metadata analysis and extraction with Essentia is the default behavior.

The Blissify analysis creates a similarity database of all songs in the music library. This can be used to automate the creation of playlists and other actions. The drawback of using Blissify is it does not add acoustic metadata to the Beets library so the results of a Blissify analysis are only available to Blissify and not Beets.

[Note:] Acoustic analysis with blissify is currently not available on Raspberry Pi installations due to lack of support for that architecture in the ffmpeg library.

It is sometimes desirable to augment one acoustic analysis with another. For example, the AcousticBrainz service seems to think a lot of songs have 0 beets per minute and tags them erroneously. After retrieving metadata using AcousticBrainz, list the songs that have a bpm value of 0:

beet list bpm:0

These songs can get an accurate setting for bpm and other audio parameters by following the mppinit -a metadata command with mpplus -X bpm:0.

Individual commands post-initialization setup

Download albums in your Bandcamp collections with mppinit bandcamp.

Download favorites in your Soundcloud account with mppinit soundcloud.

Convert WAV or M4A format media files in your library to MP3 format files with the command mpplus -F or mpplus -G. Conversion from WAV to MP3 allows these files to be imported into the Beets media library management system. Conversion from M4A (Apple ALAC) to MP3 allows these files to be streamed and played in all browsers supporting HTML5 audio (not necessary with Navidrome streaming).

If you wish to manage your music library with Beets, import the music library with the command mpplus -I.

Album cover art can be downloaded with the command mpplus -D art.

Bandcamp collections can be downloaded with the command mpplus -D bandcamp.

Soundcloud favorites can be downloaded with the command mpplus -D soundcloud.

Download additional lyrics with the command mpplus -L.

Activate the YAMS scrobbler for Last.fm with the command mpplus -Y.

Analysis and retrieval of audio-based information can be performed with the command mpplus -X 'query' where 'query' is a Beets library query. The special query term 'all' indicates the entire music library, i.e. mpplus -X all. Alternatively, query the AcousticBrainz service with mpplus -x all or create a "song similarity" database using Blissify with mpplus -B.

These common additional setup steps and more are covered in greater detail in the MusicPlayerPlus Beets README and the Post Installation Configuration section below.

Quickstart summary

To summarize, a MusicPlayer quickstart can be accomplished by:

Install the latest Arch, Debian, or RPM format installation package
Run mppinit or mppinit -l /path/to/library as your normal user
If the music library location was not properly detected:
- Configure MUSIC_DIR by editing ~/.config/mpprc
- Run the command mppinit sync
Optionally:
- Modify user-specific settings in ~/.config/mpprc and run mppinit sync
- Download albums in your Bandcamp collections with mppinit bandcamp
- Download favorites in your Soundcloud account with mppinit soundcloud
- Perform these steps with the command mppinit import
  - Convert WAV format files to MP3 format with the command mpplus -F
  - Import your music library into Beets with the command mpplus -I
- Perform these steps with the command mppinit metadata
  - Remove duplicate tracks with the command beet duplicates -d
  - Rename tracks left after duplicate removal with beet move
  - Download album cover art with the command mpplus -D art
  - Analyze and retrieve audio-based information with a command like:
  - mpplus -B creates a "song similarity" database with Blissify
    - mpplus -X all analyze the entire Beets library with Essentia
    - mpplus -X 'query' where 'query' is a Beets library query
    - mpplus -x all query AcousticBrainz for the entire Beets library
- Activate the YAMS scrobbler for Last.fm with the command mpplus -Y
- Download additional lyrics with the command mpplus -L

Full Tilt Boogie

The entire full tilt boogie initialization, for those with both Bandcamp and Soundcloud accounts with songs and albums in a collection or liked, and who wish to apply thorough, reliable, complete, and accurate metadata:

# Initialize MusicPlayerPlus, activate Music Player Daemon
# This is the only required setup step
mppinit

# For Bandcamp and Soundcloud users, a convenient way to download
mppinit bandcamp
mppinit soundcloud

# Beets library import (can take hours)
mppinit import

# Install, configure, and activate Mopidy music server
mppinit mopidy

# Install, configure, and activate Navidrome streaming music server
mppinit navidrome

# Perform analysis and extraction of acoustic metadata with Essentia
# This background process can take hours or even days for a large library
mppinit metadata

Installation

MusicPlayerPlus v2.0.1 and later can be installed on Linux systems using the Arch packaging format, the Debian packaging format, or the Red Hat Package Manager (RPM).

Supported platforms

MusicPlayerPlus has been tested successfully on the following platforms:

Arch Linux 2022.07.01
- MusicPlayerPlus_<version>-<release>-any.pkg.tar.zst
Ubuntu Linux 20.04
- MusicPlayerPlus_<version>-<release>.deb
Fedora Linux 36
- MusicPlayerPlus_<version>-<release>.rpm
CentOS Linux 8
- MusicPlayerPlus_<version>-<release>.rpm
Raspbian Linux 11
- MusicPlayerPlus_<version>-<release>.deb

Debian package installation

Many Linux distributions, most notably Ubuntu and its derivatives, use the Debian packaging system.

To tell if a Linux system is Debian based it is usually sufficient to check for the existence of the file /etc/debian_version and/or examine the contents of the file /etc/os-release.

To install on a Debian based Linux system, download the latest Debian format package from the MusicPlayerPlus Releases.

Install the MusicPlayerPlus package by executing the command

sudo apt install ./MusicPlayerPlus_<version>-<release>.deb

or

sudo dpkg -i ./MusicPlayerPlus_<version>-<release>.deb

or, on a Raspberry Pi:

sudo apt install ./MusicPlayerPlus_<version>-<release>.deb

or

sudo dpkg -i ./MusicPlayerPlus_<version>-<release>.deb

RPM Package installation

Red Hat Linux, SUSE Linux, and their derivatives use the RPM packaging format. RPM based Linux distributions include Fedora, AlmaLinux, CentOS, openSUSE, OpenMandriva, Mandrake Linux, Red Hat Linux, and Oracle Linux.

To install on an RPM based Linux system, download the latest RPM format package from the MusicPlayerPlus Releases.

Install the MusicPlayerPlus package by executing the command

sudo dnf localinstall ./MusicPlayerPlus_<version>-<release>.rpm

or

sudo rpm -i ./MusicPlayerPlus_<version>-<release>.rpm

Arch Package installation

Arch Linux, Manjaro, and other Arch Linux derivatives use the Pacman packaging format. In addition to Arch Linux, Arch based Linux distributions include ArchBang, Arch Linux, Artix Linux, ArchLabs, Asahi Linux, BlackArch, Chakra Linux, EndeavourOS, Frugalware Linux, Garuda Linux, Hyperbola GNU/Linux-libre, LinHES, Manjaro, Parabola GNU/Linux-libre, SteamOS, and SystemRescue.

To install on an Arch based Linux system, download the latest Pacman format package from the MusicPlayerPlus Releases.

Install the MusicPlayerPlus package by executing the command

sudo pacman -U ./MusicPlayerPlus_<version>-<release>-any.pkg.tar.zst

Post Installation Configuration

[Note:] Extensive post-installation steps are covered here. Minimal post-installation configuration required is the execution of the command mppinit. If the MPD music library is located in the default $HOME/Music directory then no further configuration may be necessary. See the Quickstart section.

After installing MusicPlayerPlus there are several recommended configuration steps. If not already configured, the MPD server will need to know where to locate your music library. This can be configured by editing the MusicPlayerPlus configuration file ~/.config/mpprc and running the command mppinit sync.

Client Configuration (required)

Initialize the MusicPlayerPlus configuration by executing the command:

mppinit

Examine the generated configuration in ~/.config/mpprc and make any desired changes.

The client configuration performed by mppinit includes the configuration of an MPD user service. The configuration, files, and folders used by this user level MPD service are stored in ~/.config/mpd/. Examine the generated MPD configuration file ~/.config/mpd/mpd.conf.

MusicPlayerPlus Configuration File

MusicPlayerPlus 2.0.1 release 3 and later provides the configuration file ~/.config/mpprc which serves as the primary source for MusicPlayerPlus user configurable settings. This configuration file is the "source of truth" for several settings including the music library location. Settings in mpprc are propogated throughout several other component's configurations.

The settings in mpprc are dynamic and preserved across command invocations. The dynamic nature of this configuration file means that options specified on the mpplus command line or in the mpplus menu system are written back out to ~/.config/mpprc so the next invocation of mpplus will use the previous invocation's options and settings as the default.

The default installed mpprc contains:

## MusicPlayerPlus runtime configuration
#
#  After modifying any of the following settings, run the command:
#    mppinit sync
#  as your normal MusicPlayerPlus user

## Music library location
#
MUSIC_DIR="~/Music"

# MPD client
MPD_CLIENT="mpcplus"

## General settings
#
# To enable any of these, set to 1
# For example, to enable cover art display in tmux sessions set COVER_ART=1
#
# Play audio during asciimatics animations
AUDIO=1
# Display cover art in tmux sessions
COVER_ART=1
# Display mpcplus and mppcava in a tmux session
USE_TMUX=1

## Terminal emulator / display mode
#
#  Can be one of: console, current, gnome, kitty, retro, simple, tilix
#  Where:
#    'console' will force a tmux session
#    'current' will force a tmux session in the current terminal window
#    'gnome' will use the gnome-terminal emulator if installed
#    'kitty' will use the Kitty terminal emulator if installed
#    'retro' will use cool-retro-term if installed
#    'simple' will use the ST terminal emulator if installed
#    'tilix' will use the Tilix terminal emulator if installed
#  Default fallback if none specified or not available is Kitty
#
#  Uncomment the preferred mode
#MPP_MODE=console
#MPP_MODE=current
#MPP_MODE=gnome
#MPP_MODE=retro
#MPP_MODE=simple
#MPP_MODE=tilix
MPP_MODE=kitty

## Service access
#
# The Bandcamp username can be found by visiting Bandcamp 'Settings' -> 'Fan'
# If you do not have a Bandcamp account, leave blank
BANDCAMP_USER=

# The Discogs username can be found by visiting discogs.com. Login, use the
# dropdown of your user icon in the upper right corner, click on 'Profile'.
# Your Discogs username is the last component of the profile URL.
DISCOGS_USER=
# The Discogs API token can be found by visiting
# https://www.discogs.com/settings/developers
DISCOGS_TOKEN=
# Location of the generated custom Discogs Obsidian vault
# Can be anywhere you have write permission
DISCOGS_DIR="~/Documents/Obsidian/Discogs"

# Your Last.fm username, api key, and api secret
# If you do not have a Last.fm account, leave blank
LASTFM_USER=
LASTFM_APIKEY=
LASTFM_SECRET=

# The Soundcloud user slug can be found by logging in to Soundcloud
# click on the username at top right then 'Profile'. The user slug
# is the last component of the URL when viewing your Soundcloud Profile.
# If you do not have a Soundcloud account, leave blank
SOUNDCLOUD_SLUG=

# Your Spotify client id and client secret
# If you do not have a Spotify account, leave blank
SPOTIFY_CLIENT=
SPOTIFY_SECRET=

# Your YouTube api key
# If you do not have a YouTube account, leave blank
YOUTUBE_APIKEY=

After mppinit completes the MusicPlayerPlus initialization, edit the ~/.config/mpprc configuration file and run mppinit sync.

MPD Music Directory Configuration

[Note:] MusicPlayerPlus version 1.0.3 release 1 and later perform an automated MPD user configuration and systemd service activation. This is performed by the mppinit command. MusicPlayerPlus 1.0.3r1 and later installations need not perform the following manual procedures but users may wish to review the automated MPD configuration and alter the default MPD music directory location.

The default MPD and mpcplus music directory is set to:

$HOME/Music

If your media library resides in another location then perform the following steps and run mppinit sync:

Edit $HOME/.config/mpprc and set the MUSIC_DIR entry to the location of your music library (e.g. vi ~/.config/mpprc)
Run the mppinit sync command

For example, to set the MPD music directory to the /u/audio/music directory, edit $HOME/.config/mpprc and change the MUSIC_DIR setting:

MUSIC_DIR="/u/audio/music"

The MUSIC_DIR location must be writeable by your user.

Any time the MPD music directory is manually modified, run mppinit sync.

Initializing the Beets media library management system

[Note:] Beets is NOT the now defunct music service purchased by Apple. It is an open source media library management system.

MusicPlayerPlus includes the Beets media library management system and preconfigured settings to allow easy integration with MPD and mpcplus. Beets is an application that catalogs your music collection, automatically improving its metadata. It then provides a suite of tools for manipulating and accessing your music. Beets includes an extensive set of plugins that can be used to enhance and extend the functionality of the media library management Beets provides. Many Beets plugins are installed and configured automatically by MusicPlayerPlus.

To get started using the Beets media library management system, it is necessary to import your music library into the Beets database. This process catalogs your music collection and improves its metadata. The default Beets configuration provided by MusicPlayerPlus moves and tags files in the music library during this process. It adds music library data to the Beets database. To import your music library into Beets, issue the following command:

mppinit import

or to skip WAV format media conversion and just perform the Beets import:

mpplus -I

[Note:] If additional songs or albums are added to the music library after the initial Beets import is performed, simply rerun mppinit import or beet import /path/to/new/items to import any new library items. To remove duplicates and retrieve metadata for the newly imported items, run mppinit metadata.

After importing the music library into Beets, try playing something with:

beet play QUERY

Where 'QUERY' is a valid Beets query. This can be a simple string like "blue" or "love" or a more complicated expression as described in the Beets query documentation. The Beets play plugin should match the query string to songs in your music library, add those songs to the MPD queue, and play them. Use beet ls QUERY to see what would be played.

[Note:] MusicPlayerPlus has configured the Beets play plugin to use the command /usr/share/musicplayerplus/scripts/mpcplay.sh to play media with this plugin. This script clears the MPD queue, adds any songs matching the query to the queue, and plays the MPD queue. In addition, two arguments are supported: --shuffle and --debug. These additional arguments are passed using the --args feature. For example, to play all media matching the string "velvet" and shuffle the order of play, issue the command beet play --args --shuffle velvet.

Example usage of the beet play command:

beet play velvet
beet play playlist:1970s
beet play --args --shuffle playlist:1990s
beet play --args "--debug --shuffle" green eyes

For instructions on Beets media library setup and use see the MusicPlayerPlus Beets README.

Learn more about the Beets media library management system at https://beets.io/

Additional metadata analysis and retrieval

MusicPlayerPlus includes two supported methods for augmenting music library metadata through acoustic analysis. These two methods are:

Essentia acoustic analysis and Beets metadata retrieval
- initialized with mppinit -e metadata
Blissify acoustic analysis of the MPD music library
- initialized with mppinit -b metadata

A third method using AcousticBrainz is no longer supported:

AcousticBrainz metadata retrieval (deprecated)
- initialized with mppinit -a metadata

Acoustic analysis with Blissify

Acoustic analysis with Blissify does not require a prior Beets import. The Blissify acoustic analysis creates a song similarity database for all the songs in the MPD music library. Initialize the Blissify database with the command blissify update <mpd music directory>. For example, assuming the default MPD music directory:

blissify update ~/Music

Blissify database initialization would have been automatically performed during setup if metadata initialization were done with:

mppinit -b metadata

After initialization of the Blissify database, the blissify command can be used to create an MPD playlist based on song similarities. For example, to make a 30 song playlist that queues the closest song to the currently playing song, then the closest song to the second song, etc, effectively making a "path" through the songs, execute the command:

blissify playlist --seed-song 30

To save the current MPD playlist (queue), execute the command:

mpc save <playlist-name>

Note that the acoustic analysis and database creation performed by Blissify does not update the Beets library database. In order to add this additional acoustic metadata to the Beets library it is necessary to perform an acoustic analysis with Essentia or acoustic metadata retrieval with AcousticBrainz, both described in the next sections.

Acoustic analysis with Essentia

After completing the Beets music library import with either mppinit import or mpplus -I, additional Beets metadata can be retrieved with the command:

mppinit -e metadata

This will identify and delete duplicate tracks, retrieve album genres, download album cover art, and optionally analyze and retrieve metadata for all songs in the music library using the Essentia extractor and Essentia trained models.

MusicPlayerPlus mppinit -e metadata uses Essentia for extracting acoustic characteristics of music, including low-level spectral information, rhythm, keys, scales, and much more, and automatic annotation by genres, moods, and instrumentation.

This is the same sort of thing that AcousticBrainz does but the AcousticBrainz project is no longer collecting data and was withdrawn in 2023. MusicPlayerPlus provides the same functionality using pre-compiled and packaged Essentia binaries and models.

However, the process of analyzing, extracting, and retrieving metadata can be time consuming for a large music library. The mppinit -e metadata command performs several metadata retrieval steps in a non-interactive manner and in the background so it can be left unattended if desired.

Acoustic retrieval with AcousticBrainz

[No longer supported]

While it still exists the AcousticBrainz service can be queried to provide a relatively quick way to update the Beets library with additional acoustic metadata. The AcousticBrainz service has already analyzed the acoustic characteristics of songs in the MusicBrainz catalog. To retrieve this metadata for songs in your music library, after Beets import is complete, run the command mppinit -a metadata. Or, at any time after Beets import run the command beet acousticbrainz. The AcousticBrainz service is no longer updated and was retired in 2023.

The individual metadata retrieval steps performed automatically by mppinit [-a|-b|-e] metadata can be performed manually using the instructions in the MusicPlayerPlus Beets README.

Activating the YAMS scrobbler for Last.fm

YAMS is an acronym for "Yet Another MPD Scrobbler". When YAMS is configured and running, any songs, artists, or albums played through MPD get "scrobbled" to Last.fm. This enables a tracking of your listening patterns and habits, creating a fairly extensive set of statistics viewable on Last.fm.

Features:

Authenticate with the new Last.fm Scrobbling API v2.0 - without the need to input/store your username/password locally.
Update your profile's "Now Playing" track via Last.fm's "Now Playing" API
Save failed scrobbles to a disk and upload them at a later date.
Timing configuration (e.g. scrobble percentage, real world timing values for scrobbling, etc.).
Prevent accidental duplicate scrobbles on rewind/playback restart/etc.
Automatic daemonization and config file generation.

In order to activate the YAMS scrobbler you will need an account with Last.fm. Free accounts with Last.fm include many of the service features and can provide extensive listening history statistics. If you do not wish to use Last.fm to analyze MPD track plays then this optional setup step can be ignored and no action is required as MusicPlayerPlus disables YAMS by default. Disable a previously activated YAMS service with the command mpplus -y.

Activate the YAMS scrobbler for Last.fm with the command:

mpplus -Y

The activation process must be run in a terminal window and will provide you with a URL. Copy the URL and navigate to it using a web browser. This will take you to Last.fm to authenticate if not already logged in and authorize YAMS access. Once access is authorized there is no need to authenticate for future Last.fm access with YAMS. There is also no need to manually run the yams command as a user service is activated to run it automatically. Basically, nothing else to do, just play music and it will be scrobbled by YAMS.

YAMS creates a configuration file $HOME/.config/yams/yams.yml.

Using YAMScrobbler with Libre.fm

YAMS works fine with Libre.fm, a Free Software replacement for Last.fm. If you prefer to use Libre.fm rather than Last.fm, do the following:

Set the base_url config variable to https://libre.fm/2.0/ in $HOME/.config/yams/yams.yml (don't forget the trailing slash!)
Delete any leftover .lastfm_session files
Authenticate like you normally would with Last.fm, however replace last.fm with libre.fm in the authorization URL printed out by YAMS

MPD Audio Output Configuration

Adjust the audio_output settings in ~/.config/mpd/mpd.conf. MPD must have at least one audio_output configured and in order to use the spectrum visualizer as configured by default it is necessary to configure a second audio_output in MPD.

The default MPD audio_output setting is PulseAudio. To modify the MPD audio output, uncomment one of ALSA, PulseAudio, or PipeWire and restart MPD.

A FIFO audio_output is used as a data source for the spectrum visualizer. To configure this output, add the following to ~/.config/mpd/mpd.conf:

audio_output {
    type            "fifo"
    name            "Visualizer feed"
    path            "~/.config/mpd/mpd.fifo"
    format          "44100:16:2"
}

An example ALSA audio_output configuration in ~/.config/mpd/mpd.conf:

audio_output {
  type    "alsa"
  name    "ALSA"
    buffer_time "50000"   # (50ms); default is 500000 microseconds (0.5s)
#  device    "hw:0,0"  # optional
#  mixer_type      "hardware"      # optional
#  mixer_device  "default"  # optional
#  mixer_control  "PCM"    # optional
#  mixer_index  "0"    # optional
}

Or, to use PulseAudio:

audio_output {
    type  "pulse"
    name  "pulse audio"
    device         "pulse"
    mixer_type      "hardware"
}

Output with PipeWire can also be configured:

audio_output {
    type  "pipewire"
    name  "PipeWire Sound Server"
}

MPD is a powerful and flexible music player server with many configuration options. Additional MPD configuration may be desired. See the MPD User's Manual

Fuzzy Finder Configuration

The fzmp command lists, searches, and selects media from the MPD library using the fzf fuzzy finder command line utility. A default fzmp configuration file for each user is created when the mppinit command is executed. The fzmp configuration file is located at:

~/.config/mpcplus/fzmp.conf

The initial default fzmp configuration should suffice for most use cases. Some of the interactive key bindings may need to be modified if they are already in use by other utilities. For example, the default key binding to switch to playlist view is 'F1' but the xfce4-terminal command binds 'F1' by default to its help window. In this case either the fzmp playlist view key binding must be changed or the XFCE4 terminal help window shortcut must be disabled.

To disable the XFCE4 terminal help window shortcut, in xfce4-terminal select:

Edit -> Preferences -> Advanced

Select the Disable help window shortcut key (F1 by default) and Close the Preferences dialog. The XFCE4 terminal help window shortcut will no longer be bound to 'F1' and no modification to the playlist view key binding for fzmp would be necessary.

To modify the fzmp playlist view key binding, edit the fzmp configuration file ~/.config/mpcplus/fzmp.conf and add a line like the following:

playlist_view_key F6

This revised configuration would change the playlist view key binding from 'F1' to 'F6' and the XFCE4 terminal help window shortcut could remain enabled and bound to 'F1'.

Several other fzmp bindings and options can be configured. See man fzmp for details.

Start MPD

[Note:] MusicPlayerPlus version 1.0.3 release 1 and later perform an automated MPD user configuration and systemd service activation. Initialization with mppinit for these installations should automatically start the user MPD service. No further action should be required for MusicPlayerPlus v1.0.3r1 or later installations.

Status of the MPD service can be checked with:

systemctl --user status mpd.service

Installation and initialization of MusicPlayerPlus prior to v1.0.3r1 will need to start mpd as a system-wide service by executing the commands:

sudo systemctl start mpd

If you want MPD to start automatically on subsequent reboots, run:

sudo systemctl enable mpd

Alternatively, if you want MPD to start automatically when a client attempts to connect:

sudo systemctl enable mpd.socket

System verification checks

Once the music directory has been set correctly, album art downloaded, music library imported, and mppinit sync has completed initialization, some system checks can optionally be performed.

Verify the mpd service is running and if not then start it:
- systemctl --user is-active mpd.service
- systemctl --user start mpd.service
Update the MPD client database:
- mpc update
Verify the mpd service is enabled and if not enable it
- systemctl --user is-enabled mpd.service
- systemctl --user enable mpd.service
Play music with mpplus
- See the online mpcpluskeys cheat sheet or man mpcpluskeys for help navigating the mpplus windows
- See the online mpplus man page or man mpplus for different ways to invoke the mpplus command

Initialize Music Database

[Note:] MusicPlayerPlus version 1.0.3 release 1 and later perform an automated MPD music database initialization during execution of mppinit.

For versions of MusicPlayerPlus prior to v1.0.3r1, initialize the music database with an MPD client and update the database. The mpcplus MPD client can be used for this or the standard mpc MPD client can be used. With mpcplus, launch the mpcplus MPD client, verify the client window has focus, and type u to update the database. With mpc simply execute the command mpc update.

If your music library is very large this process can take several minutes to complete. Once the music database has been updated you should see the songs, albums, and playlists in your music library appear in the client view.

Installing Mopidy

To install, configure, and activate Mopidy issue the command mppinit mopidy. After Mopidy initialization completes, open http://<ip address>:6680/iris. After adding music to the local music library, run mopidy local scan.

[Note:] In order to use the Mopidy-Beets extension, perform a mppinit import and optionally mppinit metadata prior to mppinit mopidy.

The default music server in MusicPlayerPlus is the Music Player Daemon (MPD). An alternate music server, Mopidy, is supported and can perform the same functions as MPD, is compatible with MPD clients, and can be extended to offer many more features.

Activating Mopidy will first deactivate MPD. The MusicPlayerPlus Mopidy activation runs as a user level system service. Configuration for Mopidy and Mopidy extensions resides in $HOME/.config/mopidy/. The MusicPlayerPlus activation of Mopidy auto-configures Mopidy and the installed extensions.

In addition to the bundled Mopidy extensions, the mppinit mopidy command installs the following Mopidy extensions:

Mopidy-Beets
- Mopidy extension for playing music from Beets' web plugin
Mopidy-Iris
- A comprehensive and mobile-friendly client that presents your library and extensions in a user-friendly and intuitive interface. Built using React and Redux
- Open http://<ip address>:6680/iris
Mopidy-Mobile
- Fully control a Mopidy music server from your mobile device
- Android App available on Google Play
- Other devices open http://IP_Address:6680 in a browser
Mopidy-Mpd
- Mopidy extension for controlling Mopidy from MPD clients
Mopidy-Podcast
- Mopidy extension for searching and browsing podcasts
Mopidy-Podcast-iTunes
- Mopidy extension for searching and browsing iTunes podcasts
Mopidy-TuneIn
- A backend for playing music from the TuneIn online radio service
Mopidy-Scrobbler
- Mopidy extension for scrobbling music to Last.fm
- Requires Last.fm username/password added to ~/.config/mopidy/mopidy.conf

Additional Mopidy extensions can be installed and configured. For example, to stream Spotify with Mopidy, install and configure the Mopidy-Spotify extension. Learn more at https://mopidy.com/ext/

[Note:] MusicPlayerPlus uses a Python virtual environment and Mopidy extensions are Python modules. In order to install a Mopidy extension it must be installed in the MusicPlayerPlus Python virtual environment. For example, to install the Mopidy Spotify extension run the following commands:

source ~/.venv/bin/activate
python3 -m pip install Mopidy-Spotify

To view the effective Mopidy configuration run the command mopidy config. This will display the full Mopidy configuration with passwords masked out so that you can safely share the output with others for debugging.

[Note:] The Mopidy MPD extension provides compatibility with MPD clients but does not implement all MPD features. MPD is much more powerful and flexible in terms of its configurable inputs and outputs. After activating Mopidy some features may not work the same as they did with MPD. For example, spectrum visualization may fail or player stats may not be available. However, Mopidy offers many features unavailable with MPD. It's a tradeoff.

To re-activate MPD and disable Mopidy, issue the command mppinit mpd. Easily switch back and forth between MPD and Mopidy with mppinit mpd and mppinit mopidy. Note that MusicPlayerPlus continues to use the configured MUSIC_DIR as the master music library location. To change the location of the music library, edit ~/.config/mpprc, set MUSIC_DIR to the new location, and run mppinit sync to synchronize the music library location across Beets, MPD, Mopidy, and downloaders.

Installing Navidrome

The default music server in MusicPlayerPlus is the Music Player Daemon (MPD). An alternate music server and streamer, Navidrome, is also supported. To install, configure, and activate Navidrome issue the command:

mppinit navidrome

The MusicPlayerPlus Navidrome activation runs as a user level system service. Configuration for Navidrome resides in $HOME/.config/navidrome/navidrome.toml. The MusicPlayerPlus activation of Navidrome auto-configures, starts, and enables the Navidrome service. The Navidrome log file can be found at $HOME/.config/navidrome/navidrome.log.

After installing Navidrome, you need to create your first user. This will be your admin user, a super user that can manage all aspects of Navidrome, including the ability to manage other users. Browse to Navidrome’s homepage at http://localhost:4533

Fill out the username and password you want to use, confirm the password and click on the “Create Admin” button. You should now be able to browse and listen to all your music.

[Note:] It usually take a couple of minutes for your music to start appearing in Navidrome’s UI. Check the logs to see what is the scan progress.

[Security Note:] Navidrome comes with an embedded, full-featured HTTP server but in order to provide additional security (e.g. SSL) Navidrome should be run behind a reverse proxy like Nginx or Apache. MusicPlayerPlus does not configure a reverse proxy for Navidrome. See the Navidrome network configuration documentation at https://www.navidrome.org/docs/usage/security/ to get started securing Navidrome. To use the MusicPlayerPlus default configuration of Navidrome, use http://... rather than https://....

If all you want is a Navidrome streaming music server and you do not care about Beets library management, additional downloads, or a Mopidy server then setup can be accomplished with just mppinit followed by mppinit navidrome.

Navidrome clients

The Navidrome self-hosted music service can stream your music to many devices.

MusicPlayerPlus tested and recommended free open source Navidrome clients:

iPhone/iPad
- iSub
Android
- Dsub
Linux/MacOS/Windows
- Sonixd

Character based terminal/console Navidrome clients:

Linux/Windows
- Jellycli
Linux
- Stmp

Navidrome clients are not installed by MusicPlayerPlus. Install Navidrome clients using your device's app store or following the installation instructions at the client link above.

If you do not have or wish to use a Navidrome client, then most modern browsers are supported Navidrome clients. To use a browser as a Navidrome web client, open the URL http://ip-address:4533 where ip-address is the IP address of the Navidrome server.

For a list of Airsonic compatible applications, see https://airsonic.github.io/docs/apps/

For a list of Subsonic compatible clients, see https://www.navidrome.org/docs/overview/#apps

Sonixd is a cross-platform desktop Subsonic client compatible with Navidrome. On Apple MacOS, install sonixd with Homebrew:

brew install --cask sonixd

Sublime is a native Subsonic client compatible with Navidrome for the Linux Desktop. See https://sublime-music.gitlab.io/sublime-music/index.html to install Sublime on a variety of Linux distributions.

Spotify and YouTube Music players

Spotify and YouTube Music players can be installed, configured, and launched via either the mpplus menu system or mppinit.

The Spotify player is the character-based spotify_player available at https://github.com/aome510/spotify-player and can be installed via the main menu (mpplus -i) or with the command mppinit spotify. This Spotify player runs in a terminal window or on the console and has full-feature parity with Spotify.

Configuration of the Spotify player is located in ~/.config/spotify-player/app.toml.

The YouTube Music player is a YouTube Music desktop app available at https://github.com/th-ch/youtube-music and bundled with custom plugins and built-in ad blocker/downloader. The YouTube Music player can be installed via the main menu (mpplus -i) or with the command mppinit youtube.

Configuration of the YouTube Music player is located in ~/.config/YouTube Music/config.json.

Terminal Emulator Support

Supported terminal emulators in MusicPlayerPlus include kitty, tilix, gnome-terminal, st, and cool-retro-term. Kitty is the default terminal emulator used by MusicPlayerPlus except on Raspberry Pi OS where st is used as the default.

[Note:] The kitty terminal emulator is very cool. A default kitty theme is provided (the 'Music Player Plus' theme) and should suffice for most users. An alternate kitty theme can be configured using the kitty themes kitten. To use this kitten, run:

kitty +kitten themes

An alternate terminal emulator can be specified on the mpplus command line:

mpplus -c ... # indicates use the current terminal and a tmux session
mpplus -e ... # indicates use the simple terminal emulator (st)
mpplus -g ... # indicates use the gnome terminal emulator
mpplus -k ... # indicates use the kitty terminal emulator
mpplus -r ... # indicates use the cool-retro-term terminal emulator
mpplus -t ... # indicates use the tilix terminal emulator

If an alternate terminal emulator is not specified on the command line then the default will be used unless console mode is detected. Console mode is used when no DISPLAY can be opened (e.g. running on a console, running over SSH without a display, running on a headless server). In console mode MusicPlayerPlus utilizes tmux sessions to display the character-based music player mpcplus and spectrum visualizer mppcava.

The mppcava spectrum visualizer looks better when the font used by the terminal emulator in which it is running is a small sized font. Some terminal emulators rely on a profile from which they draw much of their configuration. Profiles are used in MusicPlayerPlus to provide an enhanced visual presentation.

In order to use the Gnome, Simple, or Tilix terminal emulators they must be installed manually (except on Raspberry Pi OS where the Simple terminal emulator is installed if no supported terminal emulator is found). If you wish to use the Gnome, Simple, or Tilix terminal emulators, then use your system's package manager to install them prior to initializing MusicPlayerPlus with the mppinit command. If either or both of Gnome or Tilix terminal emulators are installed after MusicPlayerPlus initialization with mppinit then run mppinit profiles after installing gnome-terminal or tilix terminal emulator(s).

There are four terminal profiles in two terminal emulators used by MusicPlayerPlus. The gnome-terminal emulator and the tilix terminal emulator each have two custom profiles created during mppinit initialization. These profiles are named "MusicPlayer" and "Visualizer".

The custom MusicPlayerPlus terminal profiles are used to provide font sizes and background transparencies that enhance the visual appeal of both the MusicPlayerPlus control window and the spectrum visualizer.

To modify these terminal emulator profiles, launch the desired terminal emulator and modify the desired profile in the Preferences dialog.

Discogs User Collection

MusicPlayerPlus includes support for the auto-generation of an Obsidian vault from either a Discogs user collection or a local music library. The extremely rich data available from Discogs can be used to generate markdown format files reflecting the artists, albums, tracks, and items in your collection or library. The generated markdown reflecting your Discogs collection or music library includes a preconfigured Obsidian vault along with plugins, settings, and theme. The Obsidian Dataview plugin can be used to query the Obsidian vault in a variety of ways similar to a database of your library. Several example Dataview queries are included.

In order to use this facility, both DISCOGS_USER and DISCOGS_TOKEN must be configured in $HOME/.config/mpprc. If these are set then the resulting Obsidian vault from the either the command mppinit discogs or mppinit discogs local will be located in the folder specified by DISCOGS_DIR in mpprc.

See the Obsidian Custom Discogs README for details on setup and maintenance of a Discogs Obsidian vault.

MusicPlayerPlus Services and Clients

MusicPlayerPlus includes several services, some installed by default and others optionally installed with the mppinit command post-installation. Clients that can be used to access these services are also provided.

Services

The following services are included with MusicPlayerPlus:

Music Player Daemon (MPD)
- Installed, configured, and activated by default
MPD Stats Service
- Installed, configured, and activated by default
Beets Web Plugin Service
- Installed, configured, and activated by default
- Beets queries can be performed at http://localhost:8337
- Can be queried via API endpoints. For example:
  - curl -s http://localhost:8337/album/ | jq -r .
Mopidy Music Server
- Installed, configured, and activated with mppinit mopidy
- When activated, deactivates MPD, MPD Stats, and YAMS services
Navidrome Music Streaming Server
- Installed, configured, and activated with mppinit navidrome
YAMS Last.FM Scrobbler
- Installed, configured, and activated with mppinit yams

All of the MusicPlayerPlus services are user-level systemd services and can be controlled by the MusicPlayerPlus user without the need for root privilege. The mpplus -i interactive menu system includes menu entries for controlling each of these services as well as a status report on them by selecting the "Manage Music Services" from the Main Menu. Alternately, each service can be controlled from the command line using systemctl --user .... For example, to stop the MPD Stats Service, run the command systemctl --user stop mpdstats.

Which services should be installed and activated

Depending upon the use case and personal preference, a variety of combinations of MusicPlayerPlus services can be activated. Mopidy with the Mopidy-MPD extension conflicts with the MPD service. YAMS and MPD Stats only work with MPD. Therefore, if Mopidy is activated the MPD, YAMS, and MPD Stats services are automatically deactivated. Similarly, if the MPD service is reactivated, the YAMS and MPD Stats services are reactivated and Mopidy deactivated.

Choose which service you prefer, MPD or Mopidy, and activate it with either mppinit mopidy or mppinit mpd (after activating Mopidy then deciding to reactivate MPD). Using these two commands, mppinit mopidy and mppinit mpd, it is easy to switch between the two conflicting services.

The advantage of MPD is its stability, maturity, flexibility, power, and extensive configuration options. However, it is difficult to enable streaming with MPD. The advantage of Mopidy is its streaming capability and the variety of useful extensions, many of which are installed by default with mppinit mopidy.

An even better streaming solution is provided by Navidrome. Activating Navidrome enables access to the music library from any desktop, phone, tablet, or remote device with a browser. There are numerous Navidrome clients available for all devices and platforms. Activating Navidrome does not conflict with any of the other MusicPlayerPlus services so it can be streaming the music library while MPD or Mopidy is serving up the same library locally. Navidrome can optionally scrobble to Last.FM so if that option is enabled then deactivate the YAMS service.

[Summary] MusicPlayerPlus provides several different selections of services appropriate for a variety of use cases. All service configurations require a prior MusicPlayerPlus initialization with mppinit. Some common MusicPlayerPlus service configurations include:

Basic Music Player Daemon
- Configured automatically with mppinit
- MPD enabled and active, all other services disabled
- Use mpplus, mpcplus, mpc, etc to play music on local system
Music Player Daemon plus Beets
- Configured with mppinit import
- MPD and Beets enabled and active, all other services disabled
- Use beet ..., mpplus, mpcplus, mpc, to search, filter, play, ...
- Enables the Beets web plugin at http://<ip address>:8337
Mopidy Music Server plus Beets
- Configured with mppinit import, and mppinit mopidy
- Mopidy and Beets enabled and active, other services disabled
- Use beet ..., mpplus, mpcplus, mpc, to search, filter, play, ...
- Enables the Beets web plugin at http://<ip address>:8337
- Enables the Mopidy web client at http://<ip address>:6680
Navidrome Streaming plus Mopidy Music Server plus Beets
- Configure with mppinit import, mppinit mopidy, mppinit navidrome
- Navidrome, Mopidy and Beets enabled and active, other services disabled
- Use beet ..., mpplus, mpcplus, mpc, to search, filter, play, ...
- Enables the Beets web plugin at http://<ip address>:8337
- Enables the Mopidy web client at http://<ip address>:6680
- Enables the Navidrome web client at http://<ip address>:4533
- Supports many clients available for all desktops, tablets, and phones
- Run mppinit import after new mppinit bandcamp|soundcloud downloads
Navidrome Music Streaming Server without MPD/Mopidy/Beets
- Configure with mppinit navidrome
- No need for mppinit import|metadata|mopidy|yams
- Use mpplus -i menu system to stop and disable all other services
  - Select "Manage Music Services" from the Main Menu
  - If active, Stop and Disable MPD, Mopidy, and Beets
- Navidrome enabled and active, other services disabled
- Enables the Navidrome web client at http://<ip address>:4533
- Supports many clients available for all desktops, tablets, and phones
- No need for mppinit import after mppinit bandcamp|soundcloud downloads

Clients

The following clients are included with MusicPlayerPlus:

mpplus MusicPlayerPlus front-end
- Installed by default, see man mpplus
- Front-ends mpcplus MPD client and mppcava spectrum visualizer
- Example: mpplus
mpcplus character-based feature-full MPD client
- Installed by default, see man mpcplus
- Example: mpcplus
mpc command-line MPD client
- Installed by default, see man mpc
- Examples: mpc stop, mpc current, mpc play
beet command-line interface to Beets
- Installed by default, see man beet
- Examples: beet play jethro tull, beet info -l aqualung
Beets web client
- Installed by default
- Open http://<ip address>:8337
Mopidy web client
- Installed, configured, and activated with mppinit mopidy
- Open http://<ip address>:6680
Mopidy Iris web client
- Installed, configured, and activated with mppinit mopidy
- Open http://<ip address>:6680/iris
Mopidy-Mobile
- Installed, configured, and activated with mppinit mopidy
- Open http://<ip address>:6680/mobile
Navidrome web client
- Installed, configured, and activated with mppinit navidrome
- Open http://<ip address>:4533

Documentation

[NEW:] MusicPlayerPlus documentation is now available on Read the Docs

All MusicPlayerPlus commands have manual pages. Execute man <command-name> to view the manual page for a command. The mpplus frontend is the primary user interface for MusicPlayerPlus and the manual page for mpplus can be viewed with the command man mpplus. Most commands also have help/usage messages that can be viewed with the -u argument option, e.g. mpplus -u.

README for MusicPlayerPlus configuration

config/README.md - Overview and details of the MusicPlayerPlus configuration

README for mpcplus MPD client

mpcplus/README.md - Introduction to the mpcplus MPD client

README for tmuxp configs

config/tmuxp/README.md - How to invoke the MusicPlayerPlus provided tmuxp session configurations

Man Pages

mpplus : Primary MusicPlayerPlus user interface
mppcava : Audio Spectrum Visualizer
mppjulia : asciimatics animation of a Julia Set
mpprocks : asciimatics animation of MusicPlayerPlus intro
mppplasma : asciimatics animation with Plasma effect
mppinit : MusicPlayerPlus initialization
mppcover : Displays album cover art for currently playing song
mppdl : Downloads audio tracks from Bandcamp, Soundcloud, or a URL
mpcplus-tmux : MusicPlayerPlus in a tmux session
mpcplus : MusicPlayerPlus MPD client
mpcpluskeys : Cheat sheet for mpcplus MPD client navigation
mppsplash-tmux : MusicPlayerPlus asciimatics animations in a tmux session
mppsplash : MusicPlayerPlus asciimatics animations
mpd-configure : MPD configuration generator
mpd-monitor : Display info on currently playing MPD song
beet : Beets media library management command-line interface
beetsconfig : Beets media library management configuration
bandcamp-dl : Download Bandcamp collections
blissify : create MPD playlists using song similarity database
scdl : Download Soundcloud favorites
fzmp : List and search MPD media using fuzzy find
artist_to_albumartist : Copies the Artist tag to the AlbumArtist tag
listyt : List YouTube video titles and urls
yt-dlp : Download YouTube and other sites videos and audio
create_playlist : Create playlists using Beets queries

Usage

The primary MusicPlayerPlus user interface is the mpplus command. Execute mpplus -o to open the mpcplus MPD client and the mppcava spectrum visualizer. The command mpplus without arguments displays a series of interactive menus from which most of the MusicPlayerPlus tasks can be launched.

The mpc command provides a quick and easy command line interface to control the Music Player Daemon playback. The mpc command has many command line options, see man mpc for a full description. To get started with simple MPD playback control using mpc:

mpc toggle : start playback if stopped or paused, and pause playback if playing

mpc stop : stop playback

mpc next : move to next song in playlist

mpc prev : move to previous song in playlist

mpc volume +|- percent : increase or decrease volume by 'percent'

The beet play [QUERY] command can be used to specify a song or songs to play where 'QUERY' is a Beets query matching songs in the music library.

The usage messages for mppinit, mpplus, mpcplus, and mppcava provide a brief summary of the command line options.

mppinit performs one-time initializations.

Click here to view the

mppinit usage message

Usage: mppinit [-a] [-b] [-d] [-e] [-l music_dir] [-n] [-o] [-q] [-r] [-U] [-y] [-u] [bandcamp|cantata|discogs|discogs local|discogs upload vault folder|import|kitty|metadata|mopidy|mpd|navidrome|soundcloud|spotify|sync|yams|youtube]
Where:
	'-a' use AcousticBrainz for acoustic audio analysis [deprecated]
	'-b' use Blissify for MPD acoustic audio analysis
	'-d' install latest Beets development branch rather than
		the latest stable release (for testing purposes)
	'-e' use Essentia for Beets acoustic audio analysis (default)
	'-l music_dir' specifies the location of the music library
	'-n' indicates perform a dry run, don't do anything just tell me
	'-o' indicates overwrite any pre-existing configuration
	'-q' indicates quiet execution, no status messages
	'-r' indicates remove service
		supported service removals: mopidy navidrome
	'-U' indicates do not upgrade installed Python modules
	'-y' indicates answer 'yes' to all and proceed
	'-u' displays this usage message and exits

	'bandcamp' downloads all albums in your Bandcamp collections
	'cantata' installs the Cantata MPD graphical client
	'discogs' generates an Obsidian vault from your Discogs user collection
	'discogs local' generates an Obsidian vault from your local music library
	'discogs upload vault folder' adds the releases in 'vault' to
	Discogs user collection folder 'folder'
		(DISCOGS_USER and DISCOGS_TOKEN in '~/.config/mpprc must be set)
	'import' performs a Beets music library import
	'kitty' installs the Kitty terminal emulator
	'metadata' performs a library metadata update
	'mopidy' installs and configures Mopidy extensible music server
		Note: activating Mopidy deactivates MPD
	'mpd' activates the MPD music server and deactivates Mopidy
	'navidrome' installs and configures Navidrome music server
		Note: 'mppinit navidrome <version>' can be used to specify
		an alternate version of Navidrome to download and install
	'soundcloud' downloads all favorites in your Soundcloud account
	'spotify' installs the Spotify Music client spotify_player

	'sync' synchronizes MusicPlayerPlus configuration across configs
	'yams' activates the YAMS Last.fm scrobbler service
	'youtube' installs the YouTube Music client youtube-music


'mppinit' must be run as the MusicPlayerPlus user, not root.
'mppinit' must be run prior to 'mppinit sync', 'mppinit kitty',
	'mppinit metadata', 'mppinit bandcamp', 'mppinit mopidy',
	'mppinit navidrome', 'mppinit soundcloud', or 'mppinit import'

The mpplus command serves as a general user interface for all of the MusicPlayerPlus capabilities.

Click here to view the

mpplus usage message

Usage: mpplus [-A on|off] [-a] [-b] [-B] [-c] [-C client] [-E] [-e] [-F]
	[-f] [-G] [-g] [-D art|bandcamp|discogs|local|soundcloud] [-d music_directory]
	[-h] [-H] [-I] [-i|-o] [-jJ] [-k] [-K] [-l config|mopidy|navidrome|spotify|status]
    [-L] [-m] [-n num] [-N] [-M alsaconf|enable|disable|restart|start|stop|status]
    [-p] [-P script] [-q] [-Q] [-r] [-R] [-s song] [-S] [-t] [-T on|off] [-U vault]
	[-u] [-v viz_comm] [-w|W] [-x query] [-X query] [-y] [-Y] [-z fzmpopt] [-Z]
MPCplus/Visualizer options:
	-A 'on|off' specifies whether to display album cover art
	-C 'client' indicates use 'client' MPD client rather than mpcplus
	-E indicates do not use gradient colors for spectrum visualizer
	-f indicates fullscreen display
	-h indicates half-height for visualizer window (with -f only)
	-H indicates disable use of extended window manager hints
	-P script specifies the ASCIImatics script to run in visualizer pane
	-q indicates quarter-height for visualizer window (with -f only)
	-c indicates use current terminal emulator / console mode
	-e indicates use simple terminal emulator
	-g indicates use gnome terminal emulator
	-k indicates use kitty terminal emulator
	-r indicates use retro terminal emulator
	-t indicates use tilix terminal emulator
	-v 'viz_comm' indicates use visualizer 'viz_comm' rather than mppcava
ASCIImatics animation options:
	-a indicates play audio during ASCIImatics display
	-b indicates use backup audio during ASCIImatics display
	-j indicates use Julia Set scenes in ASCIImatics display
	-J indicates Julia Set with several runs using different parameters
	-m indicates use MusicPlayerPlus scenes in ASCIImatics display
	-n num specifies the number of times to cycle ASCIImatics scenes
	-N indicates use alternate comments in Plasma ASCIImatics scenes
	-p indicates use Plasma scenes in ASCIImatics display
	-s song specifies a song to accompany an ASCIImatics animation
		'song' can be the full pathname to an audio file or a
		relative pathname to an audio file in the MPD music library
		or /home/ronnie/Music/
	-S indicates display ASCIImatics splash animation
General options:
	-B indicates analyze MPD music dir with Blissify and exit
	-D 'art' indicates download album cover art and exit
	-D 'bandcamp' indicates download Bandcamp songs and exit
	-D 'soundcloud' indicates download Soundcloud songs and exit
	-D 'discogs' generate markdown from Discogs collection
	-D 'local' generate markdown from local music library
	-Q indicates display MusicPlayerPlus info and exit
	-U 'vault' indicates upload releases in 'vault' to Discogs collection
	-Z performs a dry run of a Discogs collection upload
	-d 'music_directory' specifies the music directory to use for
		downloaded album cover art. Without this option -D will use
		the 'MUSIC_DIR' setting in '~/.config/mpprc'
	-F indicates convert WAV format files in the music library
		to MP3 format files and exit. A subsequent 'mpplus -I' import
		will be necessary to import these newly converted music files.
	-G indicates convert M4A format files in the music library
		to MP3 format files and exit. A subsequent 'mpplus -I' import
		will be necessary to import these newly converted music files.
	-I indicates import albums and songs from 'music_directory' to beets and exit
		In conjunction with '-I', the '-A on' option disables auto-tagging
	-i indicates start mpplus in interactive mode (display the menu system)
	-o indicates start mpplus in non-interactive mode (no menu system)
	-K indicates kill MusicPlayerPlus tmux sessions and ASCIImatics scripts
	-l 'config' launches an editor in a terminal window to configure MusicPlayerPlus
	-l 'mopidy' opens Mopidy in the default browser if the Mopidy service is active
	-l 'navidrome' opens Navidrome in the default browser if the Navidrome service is active
	-l 'spotify' launches the Spotify Player in a terminal window
	-l 'status' displays services status and exits
	-L indicates download lyrics to the Beets library and exit
	-M 'action' can be used to control the Music Player Daemon (MPD)
	    or configure the ALSA sound system
		ALSA configuration will update the ALSA configuration in '/etc/asound.conf'
	-R indicates record tmux session with asciinema
		Asciinema is not installed by MusicPlayerPlus
		To record tmux sessions with asciinema, use your system's
		package manager to install it (e.g. apt install asciinema)
	-T 'on|off' specifies whether to use a tmux session
	-w indicates write metadata during beets import
	-W indicates do not write metadata during beets import
	-x 'query' uses AcousticBrainz to retrieve audio-based information
		for all music library media matching 'query' [deprecated]. A query
		of 'all' performs the retrieval on the entire music library.
	-X 'query' performs an analysis and retrieval, using Essentia,
		of audio-based information for all music library media
		matching 'query'. A query of 'all' performs the analysis
		and retrieval on the entire music library.
	-Y initializes the YAMS last.fm scrobbler service
	-y disables the YAMS last.fm scrobbler service
	-z fzmpopt specifies the fzmp option and invokes fzmp to
		list/search/select media in the MPD library.
		Valid values for fzmpopt are 'a', 'A', 'g', 'p', or 'P'
	-u displays this usage message and exits

Type 'man mpplus' for detailed usage info on mpplus
Type 'man mpcplus' for detailed usage info on the mpcplus MPD client
Type 'man mppsplash' for detailed usage info on the mppsplash command

The mpcplus command is an MPD client and acts as the primary MusicPlayerPlus music player.

Click here to view the

mpclus usage message

Usage: mpcplus [options]...
Options:
  -h [ --host ] HOST (=localhost)       connect to server at host
  -p [ --port ] PORT (=6600)            connect to server at port
  --current-song [=FORMAT(=<format string>)]
                                        print current song using given format
                                        and exit
  -c [ --config ] PATH (=~/.config/mpcplus/config AND ~/.mpcplus/config)
                                        specify configuration file(s)
  --ignore-config-errors                ignore unknown and invalid options in
                                        configuration files
  --test-lyrics-fetchers                check if lyrics fetchers work
  -b [ --bindings ] PATH (=~/.config/mpcplus/bindings AND ~/.mpcplus/bindings)
                                        specify bindings file(s)
  -s [ --screen ] SCREEN                specify the startup screen
  -S [ --slave-screen ] SCREEN          specify the startup slave screen
  -? [ --help ]                         show help message
  -v [ --version ]                      display version information
  -q [ --quiet ]                        suppress logs and excess output

The mpcplus MPD client has a customized set of key bindings that allow quick and easy control of MPD, searches, lyrics display, client navigation, and much more via the keyboard. View the mpcpluskeys man page with the command man mpcpluskeys.

The mppsplash command can be used to display a variety of character based animations optionally accompanied by audio.

Click here to view the

mppsplash usage message

Usage: mppsplash [-A] [-a] [-b] [-C] [-c num] [-d] [-jJ] [-m] [-p] [-s song] [-u]
Where:
  -A indicates use all effects
  -a indicates play audio during ASCIImatics display
  -b indicates use backup audio during ASCIImatics display
  -C indicates use alternate comments in Plasma effect
  -c num specifies the number of times to cycle
  -d indicates enable debug mode
  -j indicates use Julia Set effect
  -J indicates Julia Set with several runs using different parameters
  -m indicates use MusicPlayerPlus effect
  -p indicates use Plasma effect
  -s song specifies the audio file to play as accompaniment
    'song' can be the full pathname to an audio file or a relative
    pathname to an audio file in the MPD music library or
    $HOME/Music/
  -u displays this usage message and exits

The mppcava command is the MusicPlayerPlus custom character based audio spectrum visualizer.

Click here to view the

mppcava usage message

Usage : mppcava [options]
Visualize audio input in terminal.

Options:
    -p          path to config file
    -v          print version

Keys:
        Up        Increase sensitivity
        Down      Decrease sensitivity
        Left      Decrease number of bars
        Right     Increase number of bars
        r         Reload config
        c         Reload colors only
        f         Cycle foreground color
        b         Cycle background color
        q         Quit

All options are specified in a config file. See `$HOME/.config/mppcava/config`

Example client invocations

The mpplus command is intended to serve as the primary interface to invoke the mpcplus MPD client and mppcava spectrum visualizer. The mpplus command utilizes several different terminal emulators and can also be used to invoke any specified MPD client. Some example invocations of mpplus follow.

Open the mpcplus client and spectrum visualizer in fullscreen mode:

mpplus -f

Open the mpcplus client and mppcava visualizer in fullscreen mode using the tilix terminal emulator and displaying the visualizer using quarter-height:

mpplus -f -q -t

Open the cantata MPD graphical client and mppcava visualizer:

mpplus -C cantata

Open the mpcplus client in the cool-retro-term terminal and mppcava visualizer in kitty:

mpplus -r

Browse, list, search, and select media in the MPD library using the fzf fuzzy finder utility.

Search artist then filter by album using fzf:

mpplus -z a

Search all songs in the library using fzf:

mpplus -z A

Search the current playlist using fzf:

mpplus -z p

The mpcplus MPD client can be opened directly without using mpplus. Similarly, the mppcava spectrum visualizer can be opened directly without mpplus.

mpcplus # In one terminal window

mppcava # In another terminal window

To test the mpcplus lyrics fetchers:

mpcplus --test-lyrics-fetchers

Adding Album Cover Art

The mpcplus MPD client is a character-based application. As such, it is difficult to display graphical images. However, this limitation can be overcome using tmux and additional tools. In this way we can add album cover art to MusicPlayerPlus when using the character-based mpcplus client.

See Adding album art to MusicPlayerPlus to get started integrating album art in MusicPlayerPlus.

An album cover art downloader is included in MusicPlayerPlus. To download cover art for all of the albums in your MPD music directory, run the command:

mpplus -D art

Cover art for each album is saved as the file cover.jpg in the album folder. Existing cover art is preserved. If an album has incorrect album cover art and Beets library management has been activated with mppinit import, update the album cover art for that album with the command beet fetchart -f <query> where <query> is a Beets query that identifies that album. For example, to update the album cover art for the album "Eldorado" by Electric Light Orchestra, issue the command beet fetchart -f electric eldorado.

Custom key bindings

A few custom key bindings are configured during MusicPlayerPlus initialization with the mppinit command. These are purely for convenience and can be altered or removed if desired.

Tmux custom key bindings are defined in $HOME/.tmux.conf. MusicPlayerPlus custom key bindings for tmux sessions include the following:

[ Alt-PgDn ] - Next window
[ Shift-Right ] - Next window
[ Alt-PgUp ] - Previous window
[ Shift-Left ] - Previous window
[ Alt-x ] - Prompt to kill session
[ Alt-X ] - Kill session
[ Alt-Left ] - Move pane focus to left
[ Alt-Right ] - Move pane focus to right
[ Alt-Up ] - Move pane focus up
[ Alt-Down ] - Move pane focus down
[ Prefix q ] - Prompt to kill session
[ Prefix Q ] - Kill session

The tmux prefix key is remapped from Ctrl-b to Ctrl-a and the status bar is configured to display a Ctrl message when the prefix key is pressed.

The MusicPlayerPlus tmux customization enables tmux mouse mode. The mouse can be used to select and resize tmux panes and windows.

There are hundreds of tmux key bindings. To view the currently configured tmux key bindings, execute the command tmux list-keys.

Custom key bindings are also defined for the mpcplus music player client command. Mpcplus custom key bindings are defined in $HOME/.config/mpcplus/bindings. MusicPlayerPlus custom key bindings for mpcplus include the following:

[ Alt-c ] - Display album cover art for currently playing song
[ Alt-f ] - Open the fuzzy finder to search/select media
[ Alt-m ] - Open the MPD monitor in a terminal window
[ Alt-r ] - Raise/lower the spectrum visualizer window

Tmux session exit issues

In addition to the Alt-x and Alt-X key bindings above to kill the current tmux session, MusicPlayerPlus tmux key bindings include Ctrl-a q and Ctrl-a Q which also are mapped to kill-session in a similar manner. This is because some terminal emulators, in particular iTerm2, may already have key bindings for the Alt key or the Meta key may be something other than Alt.

In a MusicPlayerPlus tmux session, if Alt-x and Alt-X do not initiate a kill-session then use the configured tmux prefix key (e.g. Ctrl-a) followed by q or Q to exit the current tmux session.

If a MusicPlayerPlus tmux session has been initiated over SSH using the Terminal app on macOS then it may be necessary to configure the Terminal profile in use to "Use Option as Meta key" in order to recognize the custom tmux key bindings using the Alt key. To configure the Terminal app profile in this manner, go to Terminal -> Preferences -> Profiles. Select the profile you are using (usually "Basic Default") and select the Keyboard tab. Click the "Use Option as Meta key" checkbox and exit Terminal preferences.

Removal

On Debian based Linux systems where the MusicPlayerPlus package was installed using the MusicPlayerPlus Debian format package, remove the MusicPlayerPlus package by executing the command:

    sudo apt remove musicplayerplus

or

    sudo dpkg -r musicplayerplus

On RPM based Linux systems where the MusicPlayerPlus package was installed using the MusicPlayerPlus RPM format package, remove the MusicPlayerPlus package by executing the command:

    sudo dnf remove MusicPlayerPlus

or

    sudo rpm -e MusicPlayerPlus

On Arch based Linux systems where the MusicPlayerPlus package was installed using the MusicPlayerPlus Pacman format package, remove the MusicPlayerPlus package by executing the command:

    sudo pacman -Rs musicplayerplus

The MusicPlayerPlus package can be removed by executing the "Uninstall" script in the MusicPlayerPlus source directory:

    git clone https://github.com/doctorfree/MusicPlayerPlus.git
    cd MusicPlayerPlus
    ./Uninstall

Troubleshooting

Many problems encountered with MusicPlayerPlus often resolve to problems with the underlying Linux audio configuration. As a first step in troubleshooting, verify the audio subsystem is functioning properly. Most systems use either ALSA or PulseAudio and there are numerous audio test guides available.

MusicPlayerPlus includes a convenience script to test the ALSA audio subsystem. The command alsa_audio_test can be run to test your ALSA audio setup. If successful you will hear the test output of the aplay command. To view a alsa_audio_test usage message and current ALSA configuration settings, run the command alsa_audio_test -u

Another source of problems to investigate is the Music Player Daemon (MPD). This is the music streaming server that MusicPlayerPlus connects to. MPD is run as a system service that runs automatically. You can check the status of the MPD service by running the command systemctl --user status mpd. You can restart the MPD service with systemctl --user restart mpd.service. If the issue is not resolved by a restart or reboot, check the MPD log file at $HOME/.config/mpd/log looking for recent failures and exceptions.

It may be the case that the root of a problem is a missing dependency. MusicPlayerPlus should have installed any missing dependencies but one may have been overlooked, improperly installed, or subsequently removed. If the system logs or error output indicates something was "not found" then check for its existence. On Debian based systems there is a nice repository package index maintained. If a command was not found, it is often possible to simply type that command at a shell prompt and the Debian packaging system will be searched for any packages that contain a command with that name. If a likely looking package is returned, the problem may be solved by installing that package.

Finally, see the Troubleshooting section of the MusicPlayerPlus Wiki. for additional troubleshooting techniques and commonly resolved issues.

If an issue cannot be resolved and all troubleshooting efforts have failed, open an issue at MusicPlayerPlus issues. Even if you do manage to resolve an issue, it may still be helpful to report the issue at https://github.com/doctorfree/MusicPlayerPlus/issues so that a fix may be incorporated in the next release.

Known issues

Tmux key bindings in iTerm2 terminal emulator

The iTerm2 terminal emulator has built-in support for tmux. Several of the iTerm2 built-in tmux key bindings conflict with and override the default tmux key bindings and the MusicPlayerPlus custom tmux key bindings.

Unless you are quite familiar with iTerm2 and its tmux implementation, we do not recommend using iTerm2 with MusicPlayerPlus when running tmux sessions.

MusicPlayerPlus support for iTerm2 may be forthcoming in future releases but at this time iTerm2 is not a supported MusicPlayerPlus terminal emulator.

Tmux sessions over SSH to Fedora systems

A tmux session initiated over SSH to a Fedora Linux system may size the tmux panes incorrectly. This issue is not yet understood but will hopefully be addressed in a future release of MusicPlayerPlus. If, for example, a mpplus or mpcplus-tmux tmux session displays the mpcplus pane with a small height while the spectrum visualizer pane consumes most of the session window, then the mpcplus pane will need to be resized manually.

Tmux panes can be resized either using keyboard shortcuts or with the mouse.

To resize the mpcplus tmux pane using the mouse, click and drag the bottom of the upper pane in the session window. Drag the pane border down until the mpcplus display of music media appears.

To resize the mpcplus tmux pane using keyboard shortcuts, use one of the default tmux key bindings:

bind-key -r -T prefix       M-Up              resize-pane -U 5
bind-key -r -T prefix       M-Down            resize-pane -D 5
bind-key -r -T prefix       M-Left            resize-pane -L 5
bind-key -r -T prefix       M-Right           resize-pane -R 5
bind-key -r -T prefix       C-Up              resize-pane -U
bind-key -r -T prefix       C-Down            resize-pane -D
bind-key -r -T prefix       C-Left            resize-pane -L
bind-key -r -T prefix       C-Right           resize-pane -R

This means you can resize a pane by <prefix> Alt ↓ (tmux prefix followed by "Alt-DownArrow"). The default MusicPlayerPlus tmux prefix is Ctrl-a so in order to resize the mpcplus pane using the keyboard, type Ctrl-a then type Alt ↓. You can repeat Alt ↓ several times without needing to re-type the Ctrl-a prefix if you type it fast enough (about a second). If the display of Ctrl on the tmux status line disappears and you still need to resize the mpcplus pane, then you will need to re-type the prefix key Ctrl-a.

This issue has only been detected on Fedora Linux over SSH. However, it may occur with other systems and may not be exclusive to either SSH or Fedora.

Infrared remote control of MPD

Advanced users may wish to add remote control capabilities to MusicPlayerPlus. Getting IR remote control of MPD working is pretty geeky and fun. Also cool.

This can be accomplished on most Linux systems using LIRC (Linux Infrared Remote Control). LIRC setup and usage is described at https://wiki.archlinux.org/title/LIRC

To get started, see the ArchLinux Step-by-step LIRC setup guide for USB IR receiver with universal remote control.

The only prerequisites are a USB IR receiver, preferably an MCE model, and an old universal remote control you have lying around the house.

A long list of LIRC supported remotes with corresponding LIRC configurations can be found at the LIRC Remotes Databass.

The hard part is getting the remote control device talking to the IR receiver since there are a number of different protocols and devices supported. The LIRC setup guide linked above has pretty good step-by-step procedures for establishing communication between the remote and the receiver.

Once the hardware is successfully communicating, you can control MPD with lirc and mpc by configuring lirc. For example, add the following to ~/.lircrc:

## irexec
begin
     prog = irexec
     button = play_pause
     config = mpc toggle
     repeat = 0
end

begin
     prog = irexec
     button = stop
     config = mpc stop
     repeat = 0
end
begin
     prog = irexec
     button = previous
     config = mpc prev
     repeat = 0
end
begin
     prog = irexec
     button = next
     config = mpc next
     repeat = 0
end
begin
     prog = irexec
     button = volup
     config = mpc volume +2
     repeat = 1
end
begin
     prog = irexec
     button = voldown
     config = mpc volume -2
     repeat = 1
end
begin
     prog = irexec
     button = pbc
     config = mpc random
     repeat = 0
end
begin
     prog = irexec
     button = pdvd
     config = mpc update
     repeat = 0
end
begin
     prog = irexec
     button = right
     config = mpc seek +00:00:05
     repeat = 0
end
begin
     prog = irexec
     button = left
     config = mpc seek -00:00:05
     repeat = 0
end
begin
     prog = irexec
     button = up
     config = mpc seek +1%
     repeat = 0
end
begin
     prog = irexec
     button = down
     config = mpc seek -1%
     repeat = 0
end

A guide for configuring lirc to control MPD using mpc can be found at https://wiki.archlinux.org/title/Music_Player_Daemon/Tips_and_tricks#Control_MPD_with_lirc

Screenshots

Videos

Building MusicPlayerPlus from source

MusicPlayerPlus can be packaged and installed from the source code repository. This should be done as a normal user with sudo privileges:

# Retrieve the source code from the repository
git clone https://github.com/doctorfree/MusicPlayerPlus.git
# Enter the MusicPlayerPlus source directory
cd MusicPlayerPlus
# Create an installation package
./mkpkg
# Install MusicPlayerPlus and its dependencies
./Install

These steps are detailed below.

Clone MusicPlayerPlus repository

git clone https://github.com/doctorfree/MusicPlayerPlus.git
cd MusicPlayerPlus

[Note:] The mkpkg script in the top level of the MusicPlayerPlus repository can be used to build an installation package on all supported platforms. After cloning, cd MusicPlayerPlus and ./mkpkg. The resulting installation package(s) will be found in ./releases/<version>/.

Install packaging dependencies

MusicPlayerPlus components have packaging dependencies on the following:

On Debian based systems like Ubuntu Linux, install packaging dependencies via:

sudo apt install dpkg

On RPM based systems like Fedora Linux, install packaging dependencies via:

sudo dnf install rpm-build rpm-devel rpmlint rpmdevtools

Build and package MusicPlayerPlus

To build and package MusicPlayerPlus, execute the command:

./mkpkg

On Debian based systems like Ubuntu Linux, the mkpkg scripts executes scripts/mkdeb.sh.

On RPM based systems like Fedora Linux, the mkpkg scripts executes scripts/mkrpm.sh.

On PKGBUILD based systems like Arch Linux, the mkpkg scripts executes scripts/mkaur.sh.

Install MusicPlayerPlus from source build

After successfully building and packaging MusicPlayerPlus with ./mkpkg, install the MusicPlayerPlus package with the command:

./Install

Contributing

There are a variety of ways to contribute to the MusicPlayerPlus project. All forms of contribution are appreciated and valuable. Also, it's fun to collaborate. Here are a few ways to contribute to the further improvement and evolution of MusicPlayerPlus:

Testing and Issue Reporting

MusicPlayerPlus is fairly complex with many components, features, options, configurations, and use cases. Although currently only supported on Linux platforms, there are a plethora of Linux platforms on which MusicPlayerPlus can be deployed. Testing all of the above is time consuming and tedious. If you have a Linux platform on which you can install MusicPlayerPlus and you have the time and will to put it through its paces, then issue reports on problems you encounter would greatly help improve the robustness and quality of MusicPlayerPlus. Open issue reports at https://github.com/doctorfree/MusicPlayerPlus/issues

Sponsor MusicPlayerPlus

MusicPlayerPlus is completely free and open source software. All of the MusicPlayerPlus components are freely licensed and may be copied, modified, and redistributed freely. Nobody gets paid, nobody is making any money, it's a project fully motivated by curiousity and love of music. However, it does take some money to procure development and testing resources. Right now MusicPlayerPlus needs a multi-boot test platform to extend support to a wider variety of Linux platforms and potentially Mac OS X.

If you have the means and you would like to sponsor MusicPlayerPlus development, testing, platform support, and continued improvement then your monetary support could play a very critical role. A little bit goes a long way in MusicPlayerPlus. For example, a bootable USB SSD device could serve as a means of porting and testing support for additional platforms. Or, a decent cup of coffee could be the difference between a bug filled release and a glorious musical adventure.

Sponsor the MusicPlayerPlus project at https://github.com/sponsors/doctorfree

Contribute to Development

If you have programming skills and find the management and ease-of-use of digital music libraries to be an interesting area, you can contribute to MusicPlayerPlus development through the standard Github "fork, clone, pull request" process. There are many guides to contributing to Github hosted open source projects on the Internet. A good one is available at https://www.dataschool.io/how-to-contribute-on-github/. Another short succinct guide is at https://gist.github.com/MarcDiethelm/7303312.

Once you have forked and cloned the MusicPlayerPlus repository, it's time to setup a development environment. Although many of the MusicPlayerPlus commands are Bash shell scripts, there are also applicatons written in C and C++ along with documentation in Markdown format, configuration files in a variety of formats, examples, screenshots, video demos, build scripts, packaging, and more.

The development environment consists of several packages needed to build, package, and test MusicPlayerPlus components. These include:

    build-essential libeigen3-dev libfftw3-dev clang
    libavcodec-dev libavformat-dev libavutil-dev libswresample-dev
    libsamplerate0-dev libtag1-dev libchromaprint-dev libmpdclient-dev
    autotools-dev autoconf libtool libboost-all-dev fftw-dev
    libiniparser-dev libyaml-dev swig python3-dev pkg-config
    libncurses-dev libasound2-dev libreadline-dev libpulse-dev
    libcurl4-openssl-dev qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools
    libavfilter-dev libavdevice-dev libsqlite3-dev

On Debian (e.g. Ubuntu), PKGBUILD (e.g. Arch) and RPM (e.g. Fedora) based systems the MusicPlayerPlus installation package can be created with the mkpkg scripts. The mkpkg script determines which platform it is on and executes the appropriate build and packaging script in the scripts/ directory. These scripts invoke the build scripts for each of the projects included with MusicPlayerPlus, populate a distribution tree, and call the respective packaging utilities. Packages are saved in the ./releases/<version>/ folder. Once a package has been created it can be installed with the Install script.

It's not necessary to have C/C++ expertise to contribute to MusicPlayerPlus development. Many of the MusicPlayerPlus commands are Bash scripts and require no compilaton. Script commands reside in the bin and share/scripts directories. To modify a shell script, install MusicPlayerPlus and edit the bin/<script> or share/scripts/<script.sh> you wish to improve. After making your changes simply copy the revised script to /usr/bin and test your changes.

Modifying the configuration files is a little more tricky. Configuration files generally live in the config directory but each has its own installation location and some are modified by the mppinit command during installation. If you are just modifying the shell scripts or configuration files then you don't need to worry about the extensive list of dependencies listed above.

Feel free to email me at github@ronrecord.com with questions or comments.

Name		Name	Last commit message	Last commit date
Latest commit History 3,119 Commits
.github		.github
beets		beets
bin		bin
config		config
docs		docs
icons		icons
man		man
markdown		markdown
music		music
pkg		pkg
screenshots		screenshots
scripts		scripts
share		share
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.readthedocs.yaml		.readthedocs.yaml
AUTHORS		AUTHORS
CHANGELOG.md		CHANGELOG.md
CNAME		CNAME
INSTALL.md		INSTALL.md
Install		Install
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
Uninstall		Uninstall
VERSION		VERSION
_config.yml		_config.yml
asound.conf.tmpl		asound.conf.tmpl
build		build
clean		clean
copyright		copyright
mkpkg		mkpkg
mkrelease		mkrelease
musicplayerplus.desktop		musicplayerplus.desktop
usage.txt		usage.txt
viewman		viewman

License

doctorfree/MusicPlayerPlus

Folders and files

Latest commit

History

Repository files navigation

Table of contents

Overview

Requirements

MusicPlayerPlus Commands

Quickstart

Required setup

Optional additional setup steps

Two step post-initialization setup

Individual commands post-initialization setup

Quickstart summary

Full Tilt Boogie

Installation

Supported platforms

Debian package installation

RPM Package installation

Arch Package installation

Post Installation Configuration

Client Configuration (required)

MusicPlayerPlus Configuration File

MPD Music Directory Configuration

Initializing the Beets media library management system

Additional metadata analysis and retrieval

Acoustic analysis with Blissify

Acoustic analysis with Essentia

Acoustic retrieval with AcousticBrainz

Activating the YAMS scrobbler for Last.fm

Using YAMScrobbler with Libre.fm

MPD Audio Output Configuration

Fuzzy Finder Configuration

Start MPD

System verification checks

Initialize Music Database

Installing Mopidy

Installing Navidrome

Navidrome clients

Spotify and YouTube Music players

Terminal Emulator Support

Discogs User Collection

MusicPlayerPlus Services and Clients

Services

Which services should be installed and activated

Clients

Documentation

README for MusicPlayerPlus configuration

README for mpcplus MPD client

README for tmuxp configs

Man Pages

Usage

Example client invocations

Adding Album Cover Art

Custom key bindings

Tmux session exit issues

Removal

Troubleshooting

Known issues

Tmux key bindings in iTerm2 terminal emulator

Tmux sessions over SSH to Fedora systems

Infrared remote control of MPD

Screenshots

Videos

Building MusicPlayerPlus from source

Clone MusicPlayerPlus repository

Install packaging dependencies

Build and package MusicPlayerPlus

Install MusicPlayerPlus from source build

Contributing

Testing and Issue Reporting

Sponsor MusicPlayerPlus

Contribute to Development

Connect

Stats

About

Topics

Resources

Packages