diff options
Diffstat (limited to 'nncmpp.adoc')
| -rw-r--r-- | nncmpp.adoc | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/nncmpp.adoc b/nncmpp.adoc new file mode 100644 index 0000000..33e2834 --- /dev/null +++ b/nncmpp.adoc @@ -0,0 +1,166 @@ +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" = "https://dnbradio.com/hi.pls" + "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). + +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 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 = { + "+" = "pulse-volume-up" + "-" = "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. + +Files +----- +*nncmpp* follows the XDG Base Directory Specification. + +_~/.config/nncmpp/nncmpp.conf_:: + The configuration file. + +_~/.local/share/nncmpp/info/_:: +_/usr/local/share/nncmpp/info/_:: +_/usr/share/nncmpp/info/_:: + 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 https://git.janouch.name/p/nncmpp to report bugs, request features, +or submit pull requests. + +See also +-------- +*mpd*(1), *pulseaudio*(1) |