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`