Document PulseAudio integration

Also, make it apparent which value comes from where.

.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 1.1.1 LANGUAGES C)
 
 # Moar warnings
 if ("${CMAKE_C_COMPILER_ID}" MATCHES "GNU" OR CMAKE_COMPILER_IS_GNUCC)
@@ -21,47 +21,94 @@ 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 ()
+
 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})
+link_directories (${curl_LIBRARY_DIRS}
+	${fftw_LIBRARY_DIRS} ${libpulse_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

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016 - 2020, Přemysl Eric Janouch <p@janouch.name>
+Copyright (c) 2016 - 2021, 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,20 @@
+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

@@ -11,9 +11,14 @@ 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.  Enough for me to use the program exclusively.  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
+the appearance and key bindings can be customized.
+
+Note that since I only use the filesystem browsing mode, that's also the only
+thing I care to implement for the time being.  Similarly, the search feature is
+known to be clumsy.
 
 image::nncmpp.png[align="center"]
 
@@ -29,9 +34,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,
+                    liberty (included), termo (included) +
+Runtime dependencies: ncursesw, libunistring, cURL,
+                      fftw3 (optional), libpulse (optional)
 
  $ git clone --recursive https://git.janouch.name/p/nncmpp.git
  $ mkdir nncmpp/build

config.h.in

@@ -1,10 +1,11 @@
 #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
 
-#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,71 @@
+#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
+UP,                 Go up a level
+MULTISELECT,        Toggle multiselect
+
+SCROLL_UP,          Scroll up
+SCROLL_DOWN,        Scroll down
+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

@@ -10,7 +10,7 @@ nncmpp - terminal-based MPD client
 
 Synopsis
 --------
-*nncmpp* [_OPTION_]...
+*nncmpp* [_OPTION_]... [_URL_ | _PATH_]...
 
 Description
 -----------
@@ -19,6 +19,10 @@ 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*::
@@ -33,33 +37,35 @@ 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
 }
 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"
 }
 ....
 
@@ -70,6 +76,49 @@ 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 +133,4 @@ or submit pull requests.
 
 See also
 --------
-*mpd*(1)
+*mpd*(1), *pulseaudio*(1)