Usage
The primary MusicPlayerPlus user interface is the mpplus
command.
The default action of the mpplus
command is to open the mpcplus
MPD client and the mppcava
spectrum visualizer. The command
mpplus -i
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.
The mppinit
performs one-time initializations:
Usage: mppinit [-a] [-b] [-d] [-e] [-l music_dir] [-o] [-q] [-r] [-U] [-y] [-u] [bandcamp|discogs|discogs local|import|kitty|metadata|mopidy|mpd|navidrome|soundcloud|sync|yams]
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
'-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
'discogs' generates an Obsidian vault from your Discogs user collection
'discogs local' generates an Obsidian vault from your local music library
(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
'sync' synchronizes MusicPlayerPlus configuration across configs
'yams' activates the YAMS Last.fm scrobbler service
'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:
Usage: mpplus [-A] [-a] [-b] [-B] [-c] [-C client] [-E] [-e] [-F] [-f]
[-G] [-g] [-D art|bandcamp|soundcloud] [-d music_directory] [-h]
[-H] [-I] [-i] [-jJ] [-k] [-K] [-L] [-m] [-n num] [-N]
[-M alsaconf|enable|disable|restart|start|stop|status] [-p]
[-P script] [-q] [-r] [-R] [-s song] [-S] [-t] [-T on|off] [-uU]
[-v viz_comm] [-w|W] [-x query] [-X query] [-y] [-Y] [-z fzmpopt]
MPCplus/Visualizer options:
-A indicates display album cover art (implies tmux session)
-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
-U indicates use tmuxp to create tmux sessions
-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/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 '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' flag disables auto-tagging
-i indicates start mpplus in interactive mode
-K indicates kill MusicPlayerPlus tmux sessions and ASCIImatics scripts
-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'. 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
The mpcplus
command is an MPD client and acts as the primary
MusicPlayerPlus music player:
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:
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:
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`