= 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 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 of posible endpoints for *alsa-dispatcher.lsp*
 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 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"
    }
    capture plughw
}
----
+
The first line in the example asserts that "dispatch" is the default
PCM.
+
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*::

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

== SEE ALSO

*newlisp*

== AUTHOR

Ralph Ronnquist <ralph.ronnquist@gmail.com>