== NAME
-alsa-dispatcher - ALSA playback priority dispatcher for temporarily
-connected playback endpoints.
+alsa-dispatcher - ALSA priority dispatcher for occasional playback
+endpoints.
== SYNOPSIS
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:
-The system setup for using *alsa-dispatcher.lsp* includes two
-configuration aspects:
+ 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).
- 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.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_.
-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.lsp"
+ 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 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).
+
+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.
+
----
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 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
projects / rrq / newlisp / alsa-dispatcher.git / blobdiff