nncmpp/nncmpp.adoc

nncmpp(1)
=========
:doctype: manpage
:manmanual: nncmpp Manual
:mansource: nncmpp {release-version}

Name
----
nncmpp - MPD client

Synopsis
--------
*nncmpp* [_OPTION_]... [_URL_ | _PATH_]...

Description
-----------
*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 they're 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.

Options
-------
*-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.

Configuration
-------------
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 doesn't need
a configuration file to work.  It is, however, likely that you'll 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 = {
  "dnbradio.com" = "http://www.dnbradio.com/hi.m3u"
  "BassDrive.com" = "http://bassdrive.com/v2/streams/BassDrive.pls"
}
....

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

// TODO: it seems like liberty should contain an includable snippet about
//   the format, which could form a part of nncmpp.conf(5).

Spectrum visualiser
-------------------
When built against the FFTW library, *nncmpp* can make use of MPD's "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 you'll
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 doesn't matter, as they're simply averaged together.

PulseAudio
----------
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.

Files
-----
*nncmpp* follows the XDG Base Directory Specification.

_~/.config/nncmpp/nncmpp.conf_::
	The configuration file.

Reporting bugs
--------------
Use https://git.janouch.name/p/nncmpp to report bugs, request features,
or submit pull requests.

See also
--------
*mpd*(1), *pulseaudio*(1)