editorial

diff --git a/alsa-dispatcher.8.adoc b/alsa-dispatcher.8.adoc
index 64e8227d39722bc68edfd7c635a91e0239369f66..34f8e4b5d61147fa8c828967ab916d216cba50c3 100644 (file)
--- a/alsa-dispatcher.8.adoc
+++ b/alsa-dispatcher.8.adoc
@@ -4,7 +4,7 @@
 
 == NAME
 
-alsa-dispatcher - ALSA playback priority dispatcher for temporarily
+alsa-dispatcher - ALSA playback priority dispatcher for occasionally
 connected playback endpoints.
 
 == SYNOPSIS
@@ -23,68 +23,92 @@ successfully opened PCM playback device.
 The program is a _newlisp_ script of manageable size which links up
 with _libasound.so_ for ALSA API actions.
 
-== CONFIGURATIONS
-
 The setup for using *alsa-dispatcher.lsp* includes two configuration
 aspects:
 
- 1. The ALSA configuration collection needs to be augmented with a
- _pcm_ block that directs playback to *alsa-dispatcher.lsp* and
- capture from, say, _plughw_ (i.e., the primary sound card).
+ 1. The ALSA configuration needs to be augmented with a _pcm_ block
+ that directs playback to *alsa-dispatcher.lsp* and capture from, say,
+ _plughw_ (i.e., the primary sound card).
 
- 2. The priority list of posible endpoints for *alsa-dispatcher.lsp*
+ 2. The priority list of possible endpoints for *alsa-dispatcher.lsp*
  is a text file named _$HOME/.alsa-dispatcher_.
 
-[]
-
-*ALSA configuration (e.g. $HOME/.asoundrc)*::
+=== ALSA configuration (e.g. $HOME/.asoundrc)
 
 The ALSA configuration collection needs to include a declaration for
 *alsa-dispatcher* as an ALSA PCM by means of a short declaration in
 the user's _$HOME/.asoundrc_ file or system-wide in
 _/etc/asoundrc.conf_ The following is an example _$HOME/.asoundrc_.
-+
+
 ----
 pcm.!default dispatch
 
 pcm.dispatch {
     type asym
     playback {
-        pcm "file:|exec /usr/local/bin/alsa-dispatcher.lsp"
+        pcm {
+           type plug
+           slave {
+               pcm "file:|exec /usr/bin/alsa-dispatcher.lsp"
+               format S16_LE; channels 2; rate 48000;
+           }
+       }
     }
     capture plughw
 }
 ----
-+
+
 The first line in the example asserts that "dispatch" is the default
-PCM.
-+
+PCM. I.e. that playback directed to "default" should be passed on to
+"dispatch".
+
 The lines below that declares the "dispatch" PCM to have its playback
 stream directed to the command _/usr/local/bin/alsa-dispatcher.lsp_
 via a pipe (that is where *alsa-dispatcher.lsp* is for this example),
 and the "dispatch" PCM capture stream is sourced from _plughw_ (i.e.
 the default sound card).
 
-*About $HOME/.alsa-dispatcher*::
+Note that the playback PCM explicitly declares the stream
+characteristica (format, channels and rate) used up by
+*alsa-dispatcher.lsp*.
+
+=== About $HOME/.alsa-dispatcher
+
+The endpoints are enumerated for *alsa-dispatcher.lsp* in a text file
+_$HOME/.alsa-dispatcher_ with one line for each PCM device. The line
+contains PCM name and optionally setting variations for that device,
+in the form of _key=value_. Currently only _latency_ may be varied.
+
+Blank lines and lines starting with "#" are comments. The following is
+an illustration example.
 
-Possible endpoints are enumerated for *alsa-dispatcher.lsp* in a text
-file _$HOME/.alsa-dispatcher_ with one line for each PCM device. The
-line contains its name and optionally some specific setting variation
-for that device. Such settings have the form of _key=value_ with space
-seapartion between settings. Blank lines and lines starting with "#"
-are comments. The following is an illustration example.
-+
 ----
 bt
+usb
 plughw
 ----
-+
+
 The example _$HOME/.alsa-dispatcher_ nominates _bt_ as the first ALSA
-PCM to try, and _plughw_ as the second (and last). This illustrates
-ain imagined setup with a bluetooth device _bt_ that should have
-priority when in use. *alsa-dispatcher.lsp* will direct playback to
-_bt_ if it is in use and otherwise fall back on _plughw_ (i.e. the
-default sound card).
+PCM to try, then the _usb_ device and the _plughw_ as the third and
+last option. It's an imagined setup with a bluetooth device _bt_ that
+should have priority when in use, next a USB sound card _usb_ as
+secondary option when in use, and thirdly the default sound card
+_plughw_.
+
+Thus, *alsa-dispatcher.lsp* will try to direct playback to _bt_ first.
+If that is not in use *alsa-dispatcher.lsp* tries to direct playback
+to _usb_ and if the is not in use either, then *alsa-dispatcher.lsp*
+directs playback to _plughw_ (i.e. the default sound card).
+
+== NOTES
+
+*alsa-dispatcher.lsp* keeps playback channeling to a selected endpoint
+as long as that is available. If the endpoint goes away, or the
+*alsa-dispatcher.lsp* program is killed, that channeling is
+interrupted. Then the original sound source (eg a browser) may
+establish a new playback sink, which would caue a new
+*alsa-dispatcher.lsp* to run through the priority list again to pick
+the first option available in the then current audio context.
 
 == SEE ALSO