Bump version

Those are general status messages, and seem to belong to the bottom.
Partially motivated by the status bar being empty when disconnected.

And add a missing window invalidation.

.clang-format

@@ -0,0 +1,32 @@
+# clang-format is fairly limited, and these rules are approximate:
+#  - array initializers can get terribly mangled with clang-format 12.0,
+#  - sometimes it still aligns with space characters,
+#  - struct name NL { NL ... NL } NL name; is unachievable.
+BasedOnStyle: GNU
+ColumnLimit: 80
+IndentWidth: 4
+TabWidth: 4
+UseTab: ForContinuationAndIndentation
+BreakBeforeBraces: Allman
+SpaceAfterCStyleCast: true
+AlignAfterOpenBracket: DontAlign
+AlignOperands: DontAlign
+AlignConsecutiveMacros: Consecutive
+AllowAllArgumentsOnNextLine: false
+AllowAllParametersOfDeclarationOnNextLine: false
+IndentGotoLabels: false
+
+# IncludeCategories has some potential, but it may also break the build.
+# Note that the documentation says the value should be "Never".
+SortIncludes: false
+
+# This is a compromise, it generally works out aesthetically better.
+BinPackArguments: false
+
+# Unfortunately, this can't be told to align to column 40 or so.
+SpacesBeforeTrailingComments: 2
+
+# liberty-specific macro body wrappers.
+MacroBlockBegin: "BLOCK_START"
+MacroBlockEnd: "BLOCK_END"
+ForEachMacros: ["LIST_FOR_EACH"]

.gitignore

@@ -7,3 +7,5 @@
 /nncmpp.files
 /nncmpp.creator*
 /nncmpp.includes
+/nncmpp.cflags
+/nncmpp.cxxflags

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required (VERSION 3.0)
-project (nncmpp VERSION 1.0.0 LANGUAGES C)
+project (nncmpp VERSION 2.0.0 LANGUAGES C)
 
 # Moar warnings
 if ("${CMAKE_C_COMPILER_ID}" MATCHES "GNU" OR CMAKE_COMPILER_IS_GNUCC)
@@ -21,47 +21,103 @@ include (AddThreads)
 find_package (Termo QUIET NO_MODULE)
 option (USE_SYSTEM_TERMO
 	"Don't compile our own termo library, use the system one" ${Termo_FOUND})
-
 if (USE_SYSTEM_TERMO)
 	if (NOT Termo_FOUND)
 		message (FATAL_ERROR "System termo library not found")
-	endif (NOT Termo_FOUND)
+	endif ()
 else ()
+	# We don't want the library to install, but EXCLUDE_FROM_ALL ignores tests
 	add_subdirectory (termo EXCLUDE_FROM_ALL)
-	# We don't have many good choices when we don't want to install it and want
-	# to support older versions of CMake; this is a relatively clean approach
-	# (other possibilities: setting a variable in the parent scope, using a
-	# cache variable, writing a special config file with build paths in it and
-	# including it here, or setting a custom property on the targets).
+	file (WRITE ${PROJECT_BINARY_DIR}/CTestCustom.cmake
+		"execute_process (COMMAND ${CMAKE_COMMAND} --build termo)")
+
+	# We don't have many good choices; this is a relatively clean approach
+	# (other possibilities: setting a variable in the parent scope, using
+	# a cache variable, writing a special config file with build paths in it
+	# and including it here, or setting a custom property on the targets)
 	get_directory_property (Termo_INCLUDE_DIRS
 		DIRECTORY termo INCLUDE_DIRECTORIES)
 	set (Termo_LIBRARIES termo-static)
 endif ()
 
+pkg_check_modules (fftw fftw3 fftw3f)
+option (WITH_FFTW "Use FFTW to enable spectrum visualisation" ${fftw_FOUND})
+if (WITH_FFTW)
+	if (NOT fftw_FOUND)
+		message (FATAL_ERROR "FFTW not found")
+	endif ()
+	list (APPEND extra_libraries ${fftw_LIBRARIES})
+endif ()
+
+pkg_check_modules (libpulse libpulse)
+option (WITH_PULSE "Enable control of PulseAudio sink volume" ${libpulse_FOUND})
+if (WITH_PULSE)
+	if (NOT libpulse_FOUND)
+		message (FATAL_ERROR "libpulse not found")
+	endif ()
+	list (APPEND extra_libraries ${libpulse_LIBRARIES})
+endif ()
+
+pkg_check_modules (x11 x11 xrender xft fontconfig)
+option (WITH_X11 "Use FFTW to enable spectrum visualisation" ${x11_FOUND})
+if (WITH_X11)
+	if (NOT x11_FOUND)
+		message (FATAL_ERROR "Some X11 libraries were not found")
+	endif ()
+	list (APPEND extra_libraries ${x11_LIBRARIES})
+endif ()
+
 include_directories (${Unistring_INCLUDE_DIRS}
-	${Ncursesw_INCLUDE_DIRS} ${Termo_INCLUDE_DIRS} ${curl_INCLUDE_DIRS})
-link_directories (${curl_LIBRARY_DIRS})
+	${Ncursesw_INCLUDE_DIRS} ${Termo_INCLUDE_DIRS} ${curl_INCLUDE_DIRS}
+	${fftw_INCLUDE_DIRS} ${libpulse_INCLUDE_DIRS} ${x11_INCLUDE_DIRS})
+link_directories (${curl_LIBRARY_DIRS}
+	${fftw_LIBRARY_DIRS} ${libpulse_LIBRARY_DIRS} ${x11_LIBRARY_DIRS})
 
 # Configuration
-include (CheckFunctionExists)
-set (CMAKE_REQUIRED_LIBRARIES ${Ncursesw_LIBRARIES})
-CHECK_FUNCTION_EXISTS ("resizeterm" HAVE_RESIZETERM)
-
 if ("${CMAKE_SYSTEM_NAME}" MATCHES "BSD")
 	# Need this for SIGWINCH in FreeBSD and OpenBSD respectively;
 	# our POSIX version macros make it undefined
 	add_definitions (-D__BSD_VISIBLE=1 -D_BSD_SOURCE=1)
+elseif (APPLE)
+	add_definitions (-D_DARWIN_C_SOURCE)
 endif ()
 
+include (CheckFunctionExists)
+set (CMAKE_REQUIRED_LIBRARIES ${Ncursesw_LIBRARIES})
+CHECK_FUNCTION_EXISTS ("resizeterm" HAVE_RESIZETERM)
+
+# -lm may or may not be a part of libc
+foreach (extra m)
+	find_library (extra_lib_${extra} ${extra})
+	if (extra_lib_${extra})
+		list (APPEND extra_libraries ${extra_lib_${extra}})
+	endif ()
+endforeach ()
+
 # Generate a configuration file
 configure_file (${PROJECT_SOURCE_DIR}/config.h.in
 	${PROJECT_BINARY_DIR}/config.h)
 include_directories (${PROJECT_SOURCE_DIR} ${PROJECT_BINARY_DIR})
 
+# Assuming a Unix-compatible system with a standalone preprocessor
+set (actions_list ${PROJECT_SOURCE_DIR}/nncmpp.actions)
+set (actions ${PROJECT_BINARY_DIR}/nncmpp-actions.h)
+add_custom_command (OUTPUT ${actions}
+	COMMAND cpp -I${PROJECT_BINARY_DIR} -P ${actions_list}
+		| grep . | tr [[\n]] ^ | sed -ne [[h; s/,[^^]*/,/g]] -e [[s/$/COUNT/]]
+			-e [[s/[^^]*/\tACTION_&/g]] -e [[s/.*/enum action {\n&\n};\n/p]]
+			-e [[g; s/,[^^]*//g; y/_/-/]] -e [[s/[^^]\{1,\}/\t"&",/g]]
+			-e [[s/.*/static const char *g_action_names[] = {\n&};\n/p]]
+			-e [[g; s/[^^]*, *//g;]] -e [[s/[^^]\{1,\}/\t"&",/g]]
+			-e [[s/.*/static const char *g_action_descriptions[] = {\n&};/p]]
+		| tr ^ [[\n]] > ${actions}
+	COMMAND test -s ${actions}
+	DEPENDS ${actions_list} ${PROJECT_BINARY_DIR}/config.h VERBATIM)
+
 # Build the main executable and link it
-add_executable (${PROJECT_NAME} ${PROJECT_NAME}.c)
+add_executable (${PROJECT_NAME} ${PROJECT_NAME}.c ${actions})
 target_link_libraries (${PROJECT_NAME} ${Unistring_LIBRARIES}
-	${Ncursesw_LIBRARIES} termo-static ${curl_LIBRARIES})
+	${Ncursesw_LIBRARIES} termo-static ${curl_LIBRARIES} ${extra_libraries})
 add_threads (${PROJECT_NAME})
 
 # Installation
@@ -72,20 +128,31 @@ install (DIRECTORY contrib DESTINATION ${CMAKE_INSTALL_DATADIR}/${PROJECT_NAME})
 
 # Generate documentation from text markup
 find_program (ASCIIDOCTOR_EXECUTABLE asciidoctor)
-if (NOT ASCIIDOCTOR_EXECUTABLE)
-	message (FATAL_ERROR "asciidoctor not found")
+find_program (A2X_EXECUTABLE a2x)
+if (NOT ASCIIDOCTOR_EXECUTABLE AND NOT A2X_EXECUTABLE)
+	message (FATAL_ERROR "Neither asciidoctor nor a2x were found")
 endif ()
 
 foreach (page ${PROJECT_NAME})
 	set (page_output "${PROJECT_BINARY_DIR}/${page}.1")
 	list (APPEND project_MAN_PAGES "${page_output}")
-	add_custom_command (OUTPUT ${page_output}
-		COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage
-			-a release-version=${PROJECT_VERSION}
-			"${PROJECT_SOURCE_DIR}/${page}.adoc"
-			-o "${page_output}"
-		DEPENDS ${page}.adoc
-		COMMENT "Generating man page for ${page}" VERBATIM)
+	if (ASCIIDOCTOR_EXECUTABLE)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage
+				-a release-version=${PROJECT_VERSION}
+				-o "${page_output}"
+				"${PROJECT_SOURCE_DIR}/${page}.adoc"
+			DEPENDS ${page}.adoc
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	elseif (A2X_EXECUTABLE)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND ${A2X_EXECUTABLE} --doctype manpage --format manpage
+				-a release-version=${PROJECT_VERSION}
+				-D "${PROJECT_BINARY_DIR}"
+				"${PROJECT_SOURCE_DIR}/${page}.adoc"
+			DEPENDS ${page}.adoc
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	endif ()
 endforeach ()
 
 add_custom_target (docs ALL DEPENDS ${project_MAN_PAGES})
@@ -97,7 +164,7 @@ foreach (page ${project_MAN_PAGES})
 endforeach ()
 
 # CPack
-set (CPACK_PACKAGE_DESCRIPTION_SUMMARY "MPD client")
+set (CPACK_PACKAGE_DESCRIPTION_SUMMARY "Terminal/X11 MPD client")
 set (CPACK_PACKAGE_VENDOR "Premysl Eric Janouch")
 set (CPACK_PACKAGE_CONTACT "Přemysl Eric Janouch <p@janouch.name>")
 set (CPACK_RESOURCE_FILE_LICENSE "${PROJECT_SOURCE_DIR}/LICENSE")

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016 - 2020, Přemysl Eric Janouch <p@janouch.name>
+Copyright (c) 2016 - 2022, Přemysl Eric Janouch <p@janouch.name>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted.

NEWS

@@ -1,3 +1,50 @@
+2.0.0 (2022-09-03)
+
+ * Added an optional X11 user interface
+
+ * Implemented mouse drags on the elapsed time gauge and the scrollbar
+
+ * Added Tab and S-Tab bindings to iterate tabs
+
+ * Added a "z" binding to center the view on the selected item
+
+ * Added a "?" binding to describe items in various tabs
+
+ * Made it possible to adjust the spectrum analyzer's FPS limit
+
+ * Moved "Disconnected" and "Connecting..." messages to the status bar
+
+ * Fixed possibility of connection timeouts with PulseAudio integration
+
+
+1.2.0 (2021-12-21)
+
+ * Added ability to control the volume of MPD's current PulseAudio sink
+
+ * Now fetching Internet stream information asynchronously
+
+ * Added basic incremental search, normally bound to C-s, in all tabs
+
+ * Fixed jumping to the beginning of the queue after deleting items
+
+
+1.1.1 (2021-11-04)
+
+ * Terminal focus in/out events no longer ring the terminall bell
+
+ * Made mouse work in non-rxvt terminals with recent xterm terminfo
+
+
+1.1.0 (2021-10-21)
+
+ * Now requesting and processing terminal de/focus events,
+   using a new "defocused" attribute for selected rows
+
+ * Made it possible to show a spectrum visualiser when built against FFTW
+
+ * Any program arguments are now added to MPD's current playlist
+
+
 1.0.0 (2020-11-05)
 
  * Coming with a real manual page instead of a help2man-generated stub

README.adoc

@@ -1,19 +1,27 @@
 nncmpp
 ======
 
-'nncmpp' is yet another MPD client.  It is in effect a simplified TUI version
-of Sonata.  I had already written a lot of the required code before, so I had
-the perfect opportunity to get rid of the unmaintained Python application and
-make the first TUI client that doesn't feel awkward to use.
+'nncmpp' is yet another MPD client.  Its specialty is running equally well in
+the terminal, or as an X11 client--it will provide the same keyboard- and
+mouse-friendly interface.
+
+This project began its life as a simplified TUI version of Sonata.  I had
+already written a lot of the required code before, so I had the perfect
+opportunity to get rid of the unmaintained Python application, and to make
+the first TUI client that doesn't feel awkward to use.
 
 If it's not obvious enough, the name is a pun on all those ridiculous client
 names, and should be pronounced as "nincompoop".
 
 Features
 --------
-Most things are there.  Enough for me to use it exclusively.  Note that since I
-only use the filesystem browsing mode, that's also the only thing I care to
-implement for the time being.
+Most stuff is there.  I've been using the program exclusively for many years.
+Among other things, it can display and change PulseAudio volume directly
+to cover the use case of remote control, it has a fast spectrum visualiser,
+and both its appearance and key bindings can be customized.
+
+Note that currently only the filesystem browsing mode is implemented,
+and the search feature is known to be clumsy.
 
 image::nncmpp.png[align="center"]
 
@@ -29,9 +37,10 @@ The rest of this README will concern itself with externalities.
 
 Building
 --------
-Build dependencies: CMake, pkg-config, asciidoctor, liberty (included),
-                    termo (included) +
-Runtime dependencies: ncursesw, libunistring, cURL
+Build dependencies: CMake, pkg-config, asciidoctor or asciidoc,
+                    liberty (included), termo (included) +
+Runtime dependencies: ncursesw, libunistring, cURL +
+Optional runtime dependencies: fftw3, libpulse, x11, xft
 
  $ git clone --recursive https://git.janouch.name/p/nncmpp.git
  $ mkdir nncmpp/build
@@ -48,16 +57,19 @@ Or you can try telling CMake to make a package for you.  For Debian it is:
  $ cpack -G DEB
  # dpkg -i nncmpp-*.deb
 
-Terminal caveats
-----------------
-This application aspires to be as close to a GUI as possible.  It expects you
-to use the mouse (though it's not required).  Terminals are, however, somewhat
-tricky to get consistent results on, so be aware of the following:
+User interface caveats
+----------------------
+The ncurses interface aspires to be as close to a GUI as possible.  Don't shy
+away from using your mouse (though keyboard is also fine).  Terminals are,
+however, tricky to get consistent results on, so be aware of the following:
 
  - use a UTF-8 locale to get finer resolution progress bars and scrollbars
  - Xterm needs `XTerm*metaSendsEscape: true` for the default bindings to work
  - urxvt's 'vtwheel' plugin sabotages scrolling
 
+The X11 graphical interface is a second-class citizen, so some limitations of
+terminals carry over, such as the plain default theme.
+
 Contributing and Support
 ------------------------
 Use https://git.janouch.name/p/nncmpp to report any bugs, request features,

config.h.in

@@ -1,10 +1,12 @@
 #ifndef CONFIG_H
 #define CONFIG_H
 
-#define PROGRAM_NAME "${CMAKE_PROJECT_NAME}"
+#define PROGRAM_NAME "${PROJECT_NAME}"
 #define PROGRAM_VERSION "${PROJECT_VERSION}"
 
 #cmakedefine HAVE_RESIZETERM
+#cmakedefine WITH_FFTW
+#cmakedefine WITH_PULSE
+#cmakedefine WITH_X11
 
-#endif  // ! CONFIG_H
-
+#endif  /* ! CONFIG_H */

contrib/light-theme-256.conf

@@ -12,6 +12,7 @@ colors = {
 
 	selection = "231 202"
 	multiselect = "231 88"
+	defocused = "231 250"
 	directory = "16 231 bold"
 
 	incoming = "28"

nncmpp.actions

@@ -0,0 +1,74 @@
+#include "config.h"
+
+NONE,               Do nothing
+
+QUIT,               Quit
+REDRAW,             Redraw screen
+TAB_HELP,           Switch to help tab
+TAB_LAST,           Switch to last tab
+TAB_PREVIOUS,       Switch to previous tab
+TAB_NEXT,           Switch to next tab
+
+MPD_TOGGLE,         Toggle play/pause
+MPD_STOP,           Stop playback
+MPD_PREVIOUS,       Previous song
+MPD_NEXT,           Next song
+MPD_BACKWARD,       Seek backwards
+MPD_FORWARD,        Seek forwards
+MPD_VOLUME_UP,      Increase MPD volume
+MPD_VOLUME_DOWN,    Decrease MPD volume
+
+MPD_SEARCH,         Global search
+MPD_ADD,            Add selection to playlist
+MPD_REPLACE,        Replace playlist
+MPD_REPEAT,         Toggle repeat
+MPD_RANDOM,         Toggle random playback
+MPD_SINGLE,         Toggle single song playback
+MPD_CONSUME,        Toggle consume
+MPD_UPDATE_DB,      Update MPD database
+MPD_COMMAND,        Send raw command to MPD
+
+#ifdef WITH_PULSE
+PULSE_VOLUME_UP,    Increase PulseAudio volume
+PULSE_VOLUME_DOWN,  Decrease PulseAudio volume
+PULSE_MUTE,         Toggle PulseAudio sink mute
+#endif
+
+CHOOSE,             Choose item
+DELETE,             Delete item
+DESCRIBE,           Describe item
+UP,                 Go up a level
+MULTISELECT,        Toggle multiselect
+INCREMENTAL_SEARCH, Incremental search
+
+SCROLL_UP,          Scroll up
+SCROLL_DOWN,        Scroll down
+CENTER_CURSOR,      Center the cursor
+MOVE_UP,            Move selection up
+MOVE_DOWN,          Move selection down
+
+GOTO_TOP,           Go to top
+GOTO_BOTTOM,        Go to bottom
+GOTO_ITEM_PREVIOUS, Go to previous item
+GOTO_ITEM_NEXT,     Go to next item
+GOTO_PAGE_PREVIOUS, Go to previous page
+GOTO_PAGE_NEXT,     Go to next page
+
+GOTO_VIEW_TOP,      Select top item
+GOTO_VIEW_CENTER,   Select center item
+GOTO_VIEW_BOTTOM,   Select bottom item
+
+EDITOR_CONFIRM,     Confirm input
+
+EDITOR_B_CHAR,      Go back a character
+EDITOR_F_CHAR,      Go forward a character
+EDITOR_B_WORD,      Go back a word
+EDITOR_F_WORD,      Go forward a word
+EDITOR_HOME,        Go to start of line
+EDITOR_END,         Go to end of line
+
+EDITOR_B_DELETE,    Delete last character
+EDITOR_F_DELETE,    Delete next character
+EDITOR_B_KILL_WORD, Delete last word
+EDITOR_B_KILL_LINE, Delete everything up to BOL
+EDITOR_F_KILL_LINE, Delete everything up to EOL

nncmpp.adoc

@@ -6,25 +6,33 @@ nncmpp(1)
 
 Name
 ----
-nncmpp - terminal-based MPD client
+nncmpp - MPD client
 
 Synopsis
 --------
-*nncmpp* [_OPTION_]...
+*nncmpp* [_OPTION_]... [_URL_ | _PATH_]...
 
 Description
 -----------
-*nncmpp* is a terminal-based GUI-like MPD client.  On start up it will welcome
+*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.
 
@@ -33,43 +41,89 @@ Options
 
 Configuration
 -------------
-Unless you run MPD on a remote machine, on an unusual port, or protected by
-a password, 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:
+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    = "localhost:6600"
-	password   = "<your password>"
-	root       = "~/Music"
+  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"
-	scrollbar   = ""
+  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"
+  "dnbradio.com" = "http://www.dnbradio.com/hi.m3u"
+  "BassDrive.com" = "http://bassdrive.com/v2/streams/BassDrive.pls"
 }
 ....
 
-Terminal attributes 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.
+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.
@@ -84,4 +138,4 @@ or submit pull requests.
 
 See also
 --------
-*mpd*(1)
+*mpd*(1), *pulseaudio*(1)