nncmpp/nncmpp.adoc

167 lines
5.2 KiB
Plaintext
Raw Normal View History

2020-10-26 13:24:46 +01:00
nncmpp(1)
=========
:doctype: manpage
:manmanual: nncmpp Manual
:mansource: nncmpp {release-version}
Name
----
nncmpp - MPD client
2020-10-26 13:24:46 +01:00
Synopsis
--------
*nncmpp* [_OPTION_]... [_URL_ | _PATH_]...
2020-10-26 13:24:46 +01:00
Description
-----------
*nncmpp* is a hybrid terminal/X11 MPD client. On start up it will welcome
2020-10-26 13:24:46 +01:00
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.
2020-10-26 13:24:46 +01:00
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.
2020-10-26 13:24:46 +01:00
*-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:
2020-10-26 13:24:46 +01:00
....
settings = {
2021-11-16 05:15:52 +01:00
address = "~/.mpd/mpd.socket"
password = "<your password>"
pulseaudio = on
x11_font = "sans\\-serif-11"
2020-10-26 13:24:46 +01:00
}
colors = {
2021-11-16 05:15:52 +01:00
normal = ""
highlight = "bold"
elapsed = "reverse"
remains = "ul"
tab_bar = "reverse"
tab_active = "ul"
even = ""
odd = ""
selection = "reverse"
multiselect = "-1 6"
defocused = "ul"
scrollbar = ""
2020-10-26 13:24:46 +01:00
}
streams = {
2024-02-27 00:30:39 +01:00
"dnbradio.com" = "https://dnbradio.com/hi.pls"
2021-11-16 05:15:52 +01:00
"BassDrive.com" = "http://bassdrive.com/v2/streams/BassDrive.pls"
2020-10-26 13:24:46 +01:00
}
....
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.
2020-10-26 13:24:46 +01:00
// 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 = {
2021-11-16 05:15:52 +01:00
...
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.
2021-11-16 04:46:46 +01:00
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"
2021-11-16 04:46:46 +01:00
}
....
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.
2022-09-20 12:24:00 +02:00
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.
2020-10-26 13:24:46 +01:00
Files
-----
*nncmpp* follows the XDG Base Directory Specification.
_~/.config/nncmpp/nncmpp.conf_::
The configuration file.
2022-09-20 12:24:00 +02:00
_~/.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.
2020-10-26 13:24:46 +01:00
Reporting bugs
--------------
Use https://git.janouch.name/p/nncmpp to report bugs, request features,
or submit pull requests.
See also
--------
2021-11-16 04:46:46 +01:00
*mpd*(1), *pulseaudio*(1)