Fix crash when scrolling too far up

It mostly just looked weird when the underline wasn't on the last row.

.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)
@@ -10,6 +10,14 @@ endif ()
 # For custom modules
 set (CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/liberty/cmake)
 
+# Collect important build toggles for our simple preprocessor
+# (cpp(1) isn't part of POSIX, otherwise we could reuse config.h)
+set (options)
+macro (add_option variable help value)
+	option (${ARGV})
+	list (APPEND options "${variable}=$<BOOL:${${variable}}>")
+endmacro ()
+
 # Dependencies
 find_package (Ncursesw REQUIRED)
 find_package (PkgConfig REQUIRED)
@@ -19,73 +27,145 @@ pkg_check_modules (curl REQUIRED libcurl)
 include (AddThreads)
 
 find_package (Termo QUIET NO_MODULE)
-option (USE_SYSTEM_TERMO
+add_option (USE_SYSTEM_TERMO
-	"Don't compile our own termo library, use the system one" ${Termo_FOUND})
+	"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
+	file (WRITE ${PROJECT_BINARY_DIR}/CTestCustom.cmake
-	# to support older versions of CMake; this is a relatively clean approach
+		"execute_process (COMMAND ${CMAKE_COMMAND} --build termo)")
-	# (other possibilities: setting a variable in the parent scope, using a
+
-	# cache variable, writing a special config file with build paths in it and
+	# We don't have many good choices; this is a relatively clean approach
-	# including it here, or setting a custom property on the targets).
+	# (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)
+add_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)
+add_option (WITH_PULSE
+	"Enable PulseAudio sink volume control" "${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)
+add_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})
+	${Ncursesw_INCLUDE_DIRS} ${Termo_INCLUDE_DIRS} ${curl_INCLUDE_DIRS}
-link_directories (${curl_LIBRARY_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
+include (GNUInstallDirs)
 configure_file (${PROJECT_SOURCE_DIR}/config.h.in
 	${PROJECT_BINARY_DIR}/config.h)
 include_directories (${PROJECT_SOURCE_DIR} ${PROJECT_BINARY_DIR})
 
+set (actions_list ${PROJECT_SOURCE_DIR}/nncmpp.actions)
+set (actions_awk ${PROJECT_SOURCE_DIR}/nncmpp.actions.awk)
+set (actions ${PROJECT_BINARY_DIR}/nncmpp-actions.h)
+add_custom_command (OUTPUT ${actions}
+	COMMAND env LC_ALL=C ${options}
+		awk -f ${actions_awk} ${actions_list} > ${actions}
+	DEPENDS ${actions_awk} ${actions_list} 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
-include (GNUInstallDirs)
 install (TARGETS ${PROJECT_NAME} DESTINATION ${CMAKE_INSTALL_BINDIR})
 install (FILES LICENSE DESTINATION ${CMAKE_INSTALL_DOCDIR})
 install (DIRECTORY contrib DESTINATION ${CMAKE_INSTALL_DATADIR}/${PROJECT_NAME})
+install (DIRECTORY info DESTINATION ${CMAKE_INSTALL_DATADIR}/${PROJECT_NAME})
 
 # Generate documentation from text markup
 find_program (ASCIIDOCTOR_EXECUTABLE asciidoctor)
-if (NOT ASCIIDOCTOR_EXECUTABLE)
+find_program (A2X_EXECUTABLE a2x)
-	message (FATAL_ERROR "asciidoctor not found")
+if (NOT ASCIIDOCTOR_EXECUTABLE AND NOT A2X_EXECUTABLE)
+	message (WARNING "Neither asciidoctor nor a2x were found, "
+		"falling back to a substandard manual page generator")
 endif ()
 
 foreach (page ${PROJECT_NAME})
 	set (page_output "${PROJECT_BINARY_DIR}/${page}.1")
 	list (APPEND project_MAN_PAGES "${page_output}")
+	if (ASCIIDOCTOR_EXECUTABLE)
 		add_custom_command (OUTPUT ${page_output}
 			COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage
 				-a release-version=${PROJECT_VERSION}
-			"${PROJECT_SOURCE_DIR}/${page}.adoc"
 				-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)
+	else ()
+		set (ASCIIMAN ${PROJECT_SOURCE_DIR}/liberty/tools/asciiman.awk)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND env LC_ALL=C asciidoc-release-version=${PROJECT_VERSION}
+				awk -f ${ASCIIMAN} "${PROJECT_SOURCE_DIR}/${page}.adoc"
+				> ${page_output}
+			DEPENDS ${page}.adoc ${ASCIIMAN}
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	endif ()
 endforeach ()
 
 add_custom_target (docs ALL DEPENDS ${project_MAN_PAGES})
@@ -97,7 +177,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 - 2023, 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,70 @@
+Unreleased
+
+ * Added ability to look up song lyrics,
+   using a new scriptable extension interface for the Info tab
+
+ * Improved song information shown in the window header
+
+ * Escape no longer quits the program
+
+ * X11: added support for font fallbacks and italic fonts
+
+ * X11: fixed rendering of overflowing, partially visible list items
+
+ * Added a "o" binding to select the currently playing song
+
+ * Added Readline-like M-u, M-l, M-c editor bindings
+
+ * Changed volume adjustment bindings to use +/- keys
+
+
+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,28 @@
 nncmpp
 ======
 
-'nncmpp' is yet another MPD client.  It is in effect a simplified TUI version
+'nncmpp' is yet another MPD client.  Its specialty is running equally well in
-of Sonata.  I had already written a lot of the required code before, so I had
+the terminal, or as an X11 client--it will provide the same keyboard- and
-the perfect opportunity to get rid of the unmaintained Python application and
+mouse-friendly interface.
-make the first TUI client that doesn't feel awkward to use.
+
+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
+Most stuff is there.  I've been using the program exclusively for many years.
-only use the filesystem browsing mode, that's also the only thing I care to
+Among other things, it can display and change PulseAudio volume directly
-implement for the time being.
+to cover the use case of remote control, it has a fast spectrum visualiser,
+it can be extended with plugins to fetch lyrics or other song-related info,
+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 +38,10 @@ The rest of this README will concern itself with externalities.
 
 Building
 --------
-Build dependencies: CMake, pkg-config, asciidoctor, liberty (included),
+Build dependencies: CMake, pkg-config, awk, liberty (included),
-                    termo (included) +
+ termo (included), asciidoctor or asciidoc (recommended but optional) +
-Runtime dependencies: ncursesw, libunistring, cURL
+Runtime dependencies: ncursesw, libunistring, cURL +
+Optional runtime dependencies: fftw3, libpulse, x11, xft, Perl + cURL (lyrics)
 
  $ git clone --recursive https://git.janouch.name/p/nncmpp.git
  $ mkdir nncmpp/build
@@ -48,16 +58,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
+User interface caveats
-----------------
+----------------------
-This application aspires to be as close to a GUI as possible.  It expects you
+The ncurses interface aspires to be as close to a GUI as possible.  Don't shy
-to use the mouse (though it's not required).  Terminals are, however, somewhat
+away from using your mouse (though keyboard is also fine).  Terminals are,
-tricky to get consistent results on, so be aware of the following:
+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,15 @@
 #ifndef CONFIG_H
 #define CONFIG_H
 
-#define PROGRAM_NAME "${CMAKE_PROJECT_NAME}"
+#define PROGRAM_NAME "${PROJECT_NAME}"
 #define PROGRAM_VERSION "${PROJECT_VERSION}"
 
+// We use the XDG Base Directory Specification, but may be installed anywhere.
+#define PROJECT_DATADIR "${CMAKE_INSTALL_FULL_DATADIR}"
+
 #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"

info/10-azlyrics.pl

@@ -0,0 +1,43 @@
+#!/usr/bin/env perl
+# 10-azlyrics.pl: nncmpp info plugin to fetch song lyrics on AZLyrics
+#
+# Copyright (c) 2022, Přemysl Eric Janouch <p@janouch.name>
+# SPDX-License-Identifier: 0BSD
+#
+# Inspired by a similar ncmpc plugin.
+
+use warnings;
+use strict;
+use utf8;
+use open ':std', ':utf8';
+unless (@ARGV) {
+	print "Look up on AZLyrics\n";
+	exit;
+}
+
+use Encode;
+my ($title, $artist, $album) = map {decode_utf8($_)} @ARGV;
+
+# TODO: An upgrade would be transliteration with, e.g., Text::Unidecode.
+use Unicode::Normalize;
+$artist = lc(NFD($artist)) =~ s/^the\s+//ir =~ s/[^a-z0-9]//gr;
+$title  = lc(NFD($title))  =~ s/\(.*?\)//gr =~ s/[^a-z0-9]//gr;
+
+# TODO: Consider caching the results in a location like
+# $XDG_CACHE_HOME/nncmpp/info/azlyrics/$artist-$title
+my $found = 0;
+if ($title ne '') {
+	open(my $curl, '-|', 'curl', '-sA', 'nncmpp/2.0',
+		"https://www.azlyrics.com/lyrics/$artist/$title.html") or die $!;
+	while (<$curl>) {
+		next unless /^<div>/ .. /^<\/div>/; s/<!--.*?-->//g; s/\s+$//gs;
+
+		$found = 1;
+		s/<\/?b>/\x01/g; s/<\/?i>/\x02/g; s/<br>/\n/; s/<.+?>//g;
+		s/&lt;/</g; s/&gt;/>/g; s/&quot;/"/g; s/&apos;/'/g; s/&amp;/&/g;
+		print;
+	}
+	close($curl) or die $?;
+}
+
+print "No lyrics have been found.\n" unless $found;

line-editor.c

@@ -1,7 +1,7 @@
 /*
  * line-editor.c: a line editor component for the TUI part of liberty
  *
- * Copyright (c) 2017 - 2018, Přemysl Eric Janouch <p@janouch.name>
+ * Copyright (c) 2017 - 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.
@@ -48,6 +48,10 @@ enum line_editor_action
 	LINE_EDITOR_HOME,                   ///< Go to start of line
 	LINE_EDITOR_END,                    ///< Go to end of line
 
+	LINE_EDITOR_UPCASE_WORD,            ///< Convert word to uppercase
+	LINE_EDITOR_DOWNCASE_WORD,          ///< Convert word to lowercase
+	LINE_EDITOR_CAPITALIZE_WORD,        ///< Capitalize word
+
 	LINE_EDITOR_B_DELETE,               ///< Delete last character
 	LINE_EDITOR_F_DELETE,               ///< Delete next character
 	LINE_EDITOR_B_KILL_WORD,            ///< Delete last word
@@ -185,8 +189,8 @@ line_editor_action (struct line_editor *self, enum line_editor_action action)
 		if (self->point + 1 > (int) self->len)
 			return false;
 		int i = self->point;
-		while (i < (int) self->len && self->line[i] != ' ') i++;
 		while (i < (int) self->len && self->line[i] == ' ') i++;
+		while (i < (int) self->len && self->line[i] != ' ') i++;
 		self->point = i;
 		return true;
 	}
@@ -197,6 +201,41 @@ line_editor_action (struct line_editor *self, enum line_editor_action action)
 		self->point = self->len;
 		return true;
 
+	case LINE_EDITOR_UPCASE_WORD:
+	{
+		int i = self->point;
+		for (; i < (int) self->len && self->line[i] == ' '; i++);
+		for (; i < (int) self->len && self->line[i] != ' '; i++)
+			self->line[i] = uc_toupper (self->line[i]);
+		self->point = i;
+		line_editor_changed (self);
+		return true;
+	}
+	case LINE_EDITOR_DOWNCASE_WORD:
+	{
+		int i = self->point;
+		for (; i < (int) self->len && self->line[i] == ' '; i++);
+		for (; i < (int) self->len && self->line[i] != ' '; i++)
+			self->line[i] = uc_tolower (self->line[i]);
+		self->point = i;
+		line_editor_changed (self);
+		return true;
+	}
+	case LINE_EDITOR_CAPITALIZE_WORD:
+	{
+		int i = self->point;
+		ucs4_t (*converter) (ucs4_t) = uc_totitle;
+		for (; i < (int) self->len && self->line[i] == ' '; i++);
+		for (; i < (int) self->len && self->line[i] != ' '; i++)
+		{
+			self->line[i] = converter (self->line[i]);
+			converter = uc_tolower;
+		}
+		self->point = i;
+		line_editor_changed (self);
+		return true;
+	}
+
 	case LINE_EDITOR_B_DELETE:
 	{
 		if (self->point < 1)

nncmpp.actions

@@ -0,0 +1,79 @@
+NONE,               Do nothing
+
+QUIT,               Quit
+REDRAW,             Redraw screen
+ABORT,              Abort
+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_PLAYING,       Go to playing song
+
+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_UPCASE_WORD,     Convert word to uppercase
+EDITOR_DOWNCASE_WORD,   Convert word to lowercase
+EDITOR_CAPITALIZE_WORD, Capitalize word
+
+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.actions.awk

@@ -0,0 +1,106 @@
+# nncmpp.actions.awk: produce C code for a list of user actions
+#
+# Copyright (c) 2022, Přemysl Eric Janouch <p@janouch.name>
+# SPDX-License-Identifier: 0BSD
+#
+# Usage: env LC_ALL=C A=0 B=1 awk -f nncmpp.actions.awk \
+#  nncmpp.actions > nncmpp-actions.h
+
+# --- Preprocessor -------------------------------------------------------------
+
+function fatal(message) {
+	print "// " FILENAME ":" FNR ": fatal error: " message
+	print FILENAME ":" FNR ": fatal error: " message > "/dev/stderr"
+	exit 1
+}
+
+function condition(pass,    passing, a, i) {
+	split(substr($0, RSTART + RLENGTH), a, /[[:space:]]+/)
+	if (!(1 in a))
+		fatal("missing condition")
+
+	passing = 0
+	for (i in a)
+		if (a[i] && !pass == !ENVIRON[a[i]])
+			passing = 1
+
+	while (getline > 0) {
+		if (match($0, /^[[:space:]]*[.]endif[[:space:]]*$/))
+			return 1
+
+		if (match($0, /^[[:space:]]*[.]else[[:space:]]*$/))
+			passing = !passing
+		else if (!directive() && passing)
+			process()
+	}
+
+	fatal("unterminated condition body")
+}
+
+# Multiple arguments mean logical OR, multiple directives mean logical AND.
+# Similar syntax is also used by Exim, BSD make, or various assemblers.
+#
+# Looking at what others have picked for their preprocessor syntax:
+# {OpenGL, FreeBASIC} reuse #ifdef, which would be confusing with C code around,
+# {Mental Ray, RapidQ and UniVerse BASIC} use $ifdef, NSIS has !ifdef,
+# and Verilog went for `ifdef.  Not much more can be easily found.
+function directive() {
+	sub(/#.*/, "")
+	if (match($0, /^[[:space:]]*[.]ifdef[[:space:]]+/))
+		return condition(1)
+	if (match($0, /^[[:space:]]*[.]ifndef[[:space:]]+/))
+		return condition(0)
+	if (/^[[:space:]]*[.]/)
+		fatal("unexpected or unsupported directive")
+	return 0
+}
+
+!directive() {
+	process()
+}
+
+# --- Postprocessor ------------------------------------------------------------
+
+function strip(string) {
+	gsub(/^[[:space:]]*|[[:space:]]*$/, "", string)
+	return string
+}
+
+function process(    constant, name, description) {
+	if (match($0, /,/)) {
+		constant = name = strip(substr($0, 1, RSTART - 1))
+		description = strip(substr($0, RSTART + RLENGTH))
+		gsub(/_/, "-", name)
+
+		N++
+		Constants[N] = constant
+		Names[N] = tolower(name)
+		Descriptions[N] = description
+	} else if (/[^[:space:]]/) {
+		fatal("invalid action definition syntax")
+	}
+}
+
+function tocstring(string) {
+	gsub(/\\/, "\\\\", string)
+	gsub(/"/, "\\\"", string)
+	return "\"" string "\""
+}
+
+END {
+	print "enum action {"
+	for (i in Constants)
+		print "\t" "ACTION_" Constants[i] ","
+	print "\t" "ACTION_COUNT"
+	print "};"
+	print ""
+	print "static const char *g_action_names[] = {"
+	for (i in Names)
+		print "\t" tocstring(Names[i]) ","
+	print "};"
+	print ""
+	print "static const char *g_action_descriptions[] = {"
+	for (i in Descriptions)
+		print "\t" tocstring(Descriptions[i]) ","
+	print "};"
+}

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,16 +41,18 @@ Options
 
 Configuration
 -------------
-Unless you run MPD on a remote machine, on an unusual port, or protected by
+Unless you run MPD on a remote machine, on an unusual port, protected by
-a password, the client doesn't need a configuration file to work.  It is,
+a password, or only accessible through a Unix socket, the client doesn't need
-however, likely that you'll want to customize the looks or add some streams.
+a configuration file to work.  It is, however, likely that you'll want to
-You can start off with the following snippet:
+customize the looks or add some streams.  You can start off with the following
+snippet:
 
 ....
 settings = {
-	address    = "localhost:6600"
+  address    = "~/.mpd/mpd.socket"
   password   = "<your password>"
-	root       = "~/Music"
+  pulseaudio = on
+  x11_font   = "sans\\-serif-11"
 }
 colors = {
   normal      = ""
@@ -55,6 +65,7 @@ colors = {
   odd         = ""
   selection   = "reverse"
   multiselect = "-1 6"
+  defocused   = "ul"
   scrollbar   = ""
 }
 streams = {
@@ -63,13 +74,73 @@ streams = {
 }
 ....
 
-Terminal attributes are accepted in a format similar to that of *git-config*(1),
+Terminal attributes also apply to the GUI, and are accepted in a format similar
-only named colours aren't supported.  The distribution contains example colour
+to that of *git-config*(1), only named colours aren't supported.
-schemes in the _contrib_ directory.
+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.
@@ -77,6 +148,14 @@ Files
 _~/.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,
@@ -84,4 +163,4 @@ or submit pull requests.
 
 See also
 --------
-*mpd*(1)
+*mpd*(1), *pulseaudio*(1)