= alsa-dispatcher(8)
:doctype: manpage
:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}

== NAME

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

== SYNOPSIS

*alsa-dispatcher.lsp*

== 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
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.

== CONFIGURATIONS

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
 is a text file named _$HOME/.alsa-dispatcher_.

[]

*ALSA configuration (e.g. $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"
    }
    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.
+
----
bt
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).

== SEE ALSO

*newlisp*

== AUTHOR

Ralph Ronnquist <ralph.ronnquist@gmail.com>