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

== NAME

alsa-dispatcher - ALSA priority dispatcher for occasional 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.

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

 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)

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 {
	    type plug
	    slave {
    	        pcm "file:|exec /usr/bin/alsa-dispatcher.lsp"
    		format S16_LE; channels 2; rate 48000;
	    }
	}
    }
    capture plughw
}
----

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, 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

*newlisp*

== AUTHOR

Ralph Ronnquist <ralph.ronnquist@gmail.com>