editorial

[rrq/newlisp/alsa-dispatcher.git] / alsa-dispatcher.8.adoc

diff --git a/alsa-dispatcher.8.adoc b/alsa-dispatcher.8.adoc
index 0e27fc9c4b73a88aadb2d7e18424c383ba062ef7..3261edbb2fda003ac1b7595e7fd4c2ec5ca09dbb 100644 (file)
--- a/alsa-dispatcher.8.adoc
+++ b/alsa-dispatcher.8.adoc
@@ -4,85 +4,113 @@
 
 == NAME
 
 
 == NAME
 

-alsa-dispatcher - ALSA playback priority dispatcher for temporarily
-connected playback endpoints.
+alsa-dispatcher - ALSA priority dispatcher for occasional playback
+endpoints.

 
 == SYNOPSIS
 
 
 == SYNOPSIS
 

-*alsa-dispatcher.lsp*
+*alsa-dispatcher*

 
 == DESCRIPTION
 
 
 == DESCRIPTION
 

-*alsa-dispatcher.lsp* is an ALSA utility that handles dispatch of
-audio playback via a priority list of possible endpoints. The dispatch
-logic works through the list trying to open each ALSA PCM device in
-order until one succeeds, and thereafter *alsa-dispatcher.lsp* simply
+*alsa-dispatcher* is an ALSA utility that handles dispatch of audio
+playback via a priority list of possible endpoints. The dispatch logic
+works through the list trying to open each ALSA PCM device in order
+until one succeeds, and thereafter *alsa-dispatcher* simply

 channels the playback audio stream from its standard input to the
 successfully opened PCM playback device.
 
 channels the playback audio stream from its standard input to the
 successfully opened PCM playback device.
 

-The program is a _newlisp_ script of manageable size which links up
-with _libasound.so_ for ALSA API actions.
+The setup for using *alsa-dispatcher* includes two configuration
+aspects:

 
 

-== CONFIGURATIONS
+ 1. The ALSA configuration needs to be augmented with a _pcm_ block
+ that directs playback to *alsa-dispatcher* and capture from, say,
+ _plughw_ (i.e., the primary sound card).

 
 

-The system 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).
-
- 2. The priority list for *alsa-dispatcher.lsp* of posible endpoints
+ 2. The priority list of possible endpoints for *alsa-dispatcher*

  is a text file named _$HOME/.alsa-dispatcher_.
 
  is a text file named _$HOME/.alsa-dispatcher_.
 

-[]
+=== 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 (e.g
+_/etc/asoundrc.conf_ or _/etc/alsa/conf.d/51-alsa-dispatcher.conf_)

 
 

-*ALSA configuration (e.g. $HOME/.asoundrc)*::
+The following is an example _$HOME/.asoundrc_.

 
 

-The ALSA configuration collection needs to include setup for
-*alsa-dispatcher* as an ALSA PCM by means of e.g. a short declaration
-in the user's _$HOME/.asoundrc_ file, or system-wide in
-_/etc/asoundrc.conf_ The following is an example.
-+

 ----
 pcm.!default dispatch
 
 pcm.dispatch {
     type asym
     playback {
 ----
 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"
+               format S16_LE; channels 2; rate 48000;
+           }
+       }

     }
     capture plughw
 }
 ----
     }
     capture plughw
 }
 ----

-+
-The first of those lines asserts that "dispatch" is the default
-PCM.
-+
-The lines below declares the "dispatch" PCM to have its playback
-stream directed via a pipe to the command
-_/usr/local/bin/alsa-dispatcher.lsp_ (assuming that is where
-*alsa-dispatcher.lsp* is), and its capture stream is sourced from
-_plughw_ (i.e. the default sound card).
-
-*About $HOME/.alsa-dispatcher*::
-
-The possible endpoints are enumerated in _$HOME/.alsa-dispatcher_ with
-one line for each PCM device: its name and optionally some specific
-setting variation for that device in the form of _key=value_. Blank
-lines and lines starting with "#" are comments. The following is an
-example.
-+
+
+The first line in the example asserts that "dispatch" is the default
+PCM. I.e. that playback directed to "default" should be passed on to
+"dispatch".
+
+The rest of the example declares the "dispatch" PCM to be an "asym"
+that has the playback stream directed via a pipe to the command
+_/usr/bin/alsa-dispatcher_ (which is where *alsa-dispatcher* is
+installed in this example), and further it has the capture stream
+sourced from _plughw_ (i.e. the default sound card).
+
+Note that the playback PCM explicitly declares the stream
+characteristics (format, channels and rate) as used by
+*alsa-dispatcher*.
+
+=== About $HOME/.alsa-dispatcher
+
+The endpoints are enumerated for *alsa-dispatcher* 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.
+

 ----
 bt
 ----
 bt

+usb

 plughw
 ----
 plughw
 ----

-+
+

 The example _$HOME/.alsa-dispatcher_ nominates _bt_ as the first ALSA
 The example _$HOME/.alsa-dispatcher_ nominates _bt_ as the first ALSA

-PCM to try, and then _plughw_ as the second (and last). This suggest a
-bluetooth device _bt_ that has 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 third the default sound card
+_plughw_.
+
+Thus, *alsa-dispatcher* will try to direct playback to _bt_ first. If
+that is not in use *alsa-dispatcher* tries to direct playback to _usb_
+and if the is not in use either, then *alsa-dispatcher* directs
+playback to _plughw_ (i.e. the default sound card).
+
+== NOTES
+
+*alsa-dispatcher* keeps channeling playback to a selected endpoint as
+long as that remains available. If the endpoint goes away (or the
+*alsa-dispatcher* program is killed) that channeling is interrupted.
+The original sound source (eg a browser) may then establish a new
+playback sink, which would cause a new *alsa-dispatcher* to run
+through the priority list again to pick the first option available in
+the then current audio context.
+
+The program is an embedded _newlisp_ script of manageable size that
+links up with _libasound.so_ for ALSA API actions.

 
 == SEE ALSO
 
 
 == SEE ALSO