== NAME
-alsa-dispatcher - ALSA playback priority dispatcher for temporarily
-connected playback endpoints.
+alsa-dispatcher - ALSA priority dispatcher for occasional playback
+endpoints.
== SYNOPSIS
-*alsa-dispatcher.lsp*
+*alsa-dispatcher*
== 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.
-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_.
-[]
+=== 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 "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
}
----
-+
-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
+usb
plughw
----
-+
+
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
projects / rrq / newlisp / alsa-dispatcher.git / blobdiff