You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

5.2 KiB



nncmpp - MPD client


nncmpp [OPTION]…​ [URL | PATH]…​


nncmpp is a hybrid terminal/X11 MPD client. On start up it will welcome you with an overview of all key bindings and the actions theyre assigned to. Individual tabs can be switched to either using the mouse or by pressing M-1 through M-9, corresponding to the order they appear in.

As a convenience utility, any program arguments are added to the MPD queue. Note that to add files outside the database, you need to connect to MPD using a socket file.


-d, --debug

Adds a "Debug" tab showing all MPD communication and other information that help debug various issues.

-x, --x11

Use an X11 interface even when run from a terminal. Note that the application may be built with this feature disabled.

-h, --help

Display a help message and exit.

-V, --version

Output version information and exit.


Unless you run MPD on a remote machine, on an unusual port, protected by a password, or only accessible through a Unix socket, the client doesnt need a configuration file to work. It is, however, likely that youll want to customize the looks or add some streams. You can start off with the following snippet:

settings = {
  address    = "~/.mpd/mpd.socket"
  password   = "<your password>"
  pulseaudio = on
  x11_font   = "sans\\-serif-11"
colors = {
  normal      = ""
  highlight   = "bold"
  elapsed     = "reverse"
  remains     = "ul"
  tab_bar     = "reverse"
  tab_active  = "ul"
  even        = ""
  odd         = ""
  selection   = "reverse"
  multiselect = "-1 6"
  defocused   = "ul"
  scrollbar   = ""
streams = {
  "" = ""
  "" = ""

Terminal attributes also apply to the GUI, and are accepted in a format similar to that of git-config(1), only named colours arent supported. The distribution contains example colour schemes in the contrib directory.

To adjust key bindings, put them within a normal or editor object. Run nncmpp with the --debug option to find out key combinations names. Press ? in the help tab to learn the action identifiers to use.

Spectrum visualiser

When built against the FFTW library, nncmpp can make use of MPDs "fifo" output plugin to show the audio spectrum. This has some caveats, namely that it may not be properly synchronized, only one instance of a client can read from a given named pipe at a time, it will cost you some CPU time, and finally youll need to set it up manually to match your MPD configuration, e.g.:

settings = {
  spectrum_path = "~/.mpd/mpd.fifo"  # "path"
  spectrum_format = "44100:16:2"     # "format" (samplerate:bits:channels)
  spectrum_bars = 8                  # beware of exponential complexity

The sample rate should be greater than 40 kHz, the number of bits 8 or 16, and the number of channels doesnt matter, as theyre simply averaged together.


If you find standard MPD volume control useless, you may instead configure nncmpp to show and control the volume of any PulseAudio sink MPD is currently connected to.

This feature may be enabled with the settings.pulseaudio configuration option, as in the snippet above. To replace the default volume control bindings, use:

normal = {
  "M-PageUp" = "pulse-volume-up"
  "M-PageDown" = "pulse-volume-down"

The respective actions may also be invoked from the help tab directly.

For this to work, nncmpp needs to access the right PulseAudio daemon—in case your setup is unusual, consult the list of environment variables in pulseaudio(1). MPD-compatibles are currently unsupported.

Info plugins

You can invoke various plugins from the Info tab, for example to look up song lyrics.

Plugins can be arbitrary scripts or binaries. When run without command line arguments, a plugin outputs a user interface description of what it does. When invoked by a user, it receives the following self-explanatory arguments: TITLE ARTIST [ALBUM], and anything it writes to its standard output or standard error stream is presented back to the user. Here, bold and italic formatting can be toggled with ASCII control characters 1 (SOH) and 2 (STX), respectively. Otherwise, all input and output makes use of the UTF-8 encoding.


nncmpp follows the XDG Base Directory Specification.


The configuration file.


Info plugins are loaded from these directories, in order, then listed lexicographically. Only the first occurence of a particular filename is used, and empty files act as silent disablers.

Reporting bugs

Use to report bugs, request features, or submit pull requests.

See also

mpd(1), pulseaudio(1)