Document PulseAudio integration

Also, make it apparent which value comes from where.

CMakeLists.txt

@@ -91,9 +91,10 @@ configure_file (${PROJECT_SOURCE_DIR}/config.h.in
 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 ${PROJECT_SOURCE_DIR}/nncmpp.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]]
@@ -102,7 +103,7 @@ add_custom_command (OUTPUT ${actions}
 			-e [[s/.*/static const char *g_action_descriptions[] = {\n&};/p]]
 		| tr ^ [[\n]] > ${actions}
 	COMMAND test -s ${actions}
-	DEPENDS ${PROJECT_BINARY_DIR}/config.h VERBATIM)
+	DEPENDS ${actions_list} ${PROJECT_BINARY_DIR}/config.h VERBATIM)
 
 # Build the main executable and link it
 add_executable (${PROJECT_NAME} ${PROJECT_NAME}.c ${actions})

nncmpp.actions

@@ -15,8 +15,8 @@ MPD_PREVIOUS,       Previous song
 MPD_NEXT,           Next song
 MPD_BACKWARD,       Seek backwards
 MPD_FORWARD,        Seek forwards
-MPD_VOLUME_UP,      Increase volume
-MPD_VOLUME_DOWN,    Decrease volume
+MPD_VOLUME_UP,      Increase MPD volume
+MPD_VOLUME_DOWN,    Decrease MPD volume
 
 MPD_SEARCH,         Global search
 MPD_ADD,            Add selection to playlist
@@ -31,7 +31,7 @@ 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 mute of MPD PulseAudio sink
+PULSE_MUTE,         Toggle PulseAudio sink mute
 #endif
 
 CHOOSE,             Choose item

nncmpp.adoc

@@ -45,28 +45,27 @@ snippet:
 
 ....
 settings = {
-	address    = "~/.mpd/mpd.socket"
-	password   = "<your password>"
-	root       = "~/Music"
-	pulseaudio = on
+  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"
-	defocused   = "ul"
-	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"
 }
 ....
 
@@ -87,17 +86,39 @@ 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
-	...
+  ...
+  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.
@@ -112,4 +133,4 @@ or submit pull requests.
 
 See also
 --------
-*mpd*(1)
+*mpd*(1), *pulseaudio*(1)

nncmpp.c

@@ -1243,6 +1243,7 @@ static struct app_context
 #ifdef WITH_PULSE
 	struct pulse pulse;                 ///< PulseAudio control
 #endif  // WITH_PULSE
+	bool pulse_control_requested;       ///< PulseAudio control desired by user
 
 	struct line_editor editor;          ///< Line editor
 	struct poller_idle refresh_event;   ///< Refresh the screen
@@ -1304,6 +1305,13 @@ on_poll_elapsed_time_changed (struct config_item *item)
 	g.elapsed_poll = item->value.boolean;
 }
 
+static void
+on_pulseaudio_changed (struct config_item *item)
+{
+	// This is only set once, on application startup
+	g.pulse_control_requested = item->value.boolean;
+}
+
 static struct config_schema g_config_settings[] =
 {
 	{ .name      = "address",
@@ -1340,6 +1348,7 @@ static struct config_schema g_config_settings[] =
 	{ .name      = "pulseaudio",
 	  .comment   = "Look up MPD in PulseAudio for improved volume controls",
 	  .type      = CONFIG_ITEM_BOOLEAN,
+	  .on_change = on_pulseaudio_changed,
 	  .default_  = "off" },
 #endif  // WITH_PULSE
 
@@ -1376,14 +1385,6 @@ get_config_string (struct config_item *root, const char *key)
 	return item->value.string.str;
 }
 
-static bool
-get_config_boolean (struct config_item *root, const char *key)
-{
-	struct config_item *item = config_item_get (root, key, NULL);
-	hard_assert (item && item->type == CONFIG_ITEM_BOOLEAN);
-	return item->value.boolean;
-}
-
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
 static void
@@ -1782,18 +1783,31 @@ app_draw_status (void)
 
 	// It gets a bit complicated due to the only right-aligned item on the row
 	struct str volume = str_make ();
-	int remaining = COLS - buf.total_width;
-	if (g.volume >= 0)
-	{
-		str_append (&volume, "  ");
 #ifdef WITH_PULSE
-		if (pulse_volume_status (&g.pulse, &volume))
-			str_append (&volume, " @ ");
-#endif  // WITH_PULSE
-		str_append_printf (&volume, "%3d%%", g.volume);
-		remaining -= volume.len;
-	}
+	if (g.pulse_control_requested)
+	{
+		struct str buf = str_make ();
+		if (pulse_volume_status (&g.pulse, &buf))
+		{
+			if (g.volume >= 0 && g.volume != 100)
+				str_append_printf (&buf, " (%d%%)", g.volume);
+		}
+		else
+		{
+			if (g.volume >= 0)
+				str_append_printf (&buf, "(%d%%)", g.volume);
+		}
+		if (buf.len)
+			str_append_printf (&volume, "  %s", buf.str);
 
+		str_free (&buf);
+	}
+	else
+#endif  // WITH_PULSE
+	if (g.volume >= 0)
+		str_append_printf (&volume, "  %3d%%", g.volume);
+
+	int remaining = COLS - buf.total_width - volume.len;
 	if (!stopped && g.song_elapsed >= 0 && g.song_duration >= 1
 	 && remaining > 0)
 	{
@@ -4173,7 +4187,7 @@ static void
 pulse_update (void)
 {
 	struct mpd_client *c = &g.client;
-	if (!get_config_boolean (g.config.root, "settings.pulseaudio"))
+	if (!g.pulse_control_requested)
 		return;
 
 	// The read permission is sufficient for this command