alsa-dispatcher.8.adoc

   1 = alsa-dispatcher(8)
   2 :doctype: manpage
   3 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
   4
   5 == NAME
   6
   7 alsa-dispatcher - ALSA playback priority dispatcher for occasionally
   8 connected playback endpoints.
   9
  10 == SYNOPSIS
  11
  12 *alsa-dispatcher.lsp*
  13
  14 == DESCRIPTION
  15
  16 *alsa-dispatcher.lsp* is an ALSA utility that handles dispatch of
  17 audio playback via a priority list of possible endpoints. The dispatch
  18 logic works through the list trying to open each ALSA PCM device in
  19 order until one succeeds, and thereafter *alsa-dispatcher.lsp* simply
  20 channels the playback audio stream from its standard input to the
  21 successfully opened PCM playback device.
  22
  23 The program is a _newlisp_ script of manageable size which links up
  24 with _libasound.so_ for ALSA API actions.
  25
  26 The setup for using *alsa-dispatcher.lsp* includes two configuration
  27 aspects:
  28
  29  1. The ALSA configuration needs to be augmented with a _pcm_ block
  30  that directs playback to *alsa-dispatcher.lsp* and capture from, say,
  31  _plughw_ (i.e., the primary sound card).
  32
  33  2. The priority list of possible endpoints for *alsa-dispatcher.lsp*
  34  is a text file named _$HOME/.alsa-dispatcher_.
  35
  36 === ALSA configuration (e.g. $HOME/.asoundrc)
  37
  38 The ALSA configuration collection needs to include a declaration for
  39 *alsa-dispatcher* as an ALSA PCM by means of a short declaration in
  40 the user's _$HOME/.asoundrc_ file or system-wide in
  41 _/etc/asoundrc.conf_ The following is an example _$HOME/.asoundrc_.
  42
  43 ----
  44 pcm.!default dispatch
  45
  46 pcm.dispatch {
  47     type asym
  48     playback {
  49         pcm {
  50             type plug
  51             slave {
  52                 pcm "file:|exec /usr/bin/alsa-dispatcher.lsp"
  53                 format S16_LE; channels 2; rate 48000;
  54             }
  55         }
  56     }
  57     capture plughw
  58 }
  59 ----
  60
  61 The first line in the example asserts that "dispatch" is the default
  62 PCM. I.e. that playback directed to "default" should be passed on to
  63 "dispatch".
  64
  65 The lines below that declares the "dispatch" PCM to have its playback
  66 stream directed to the command _/usr/local/bin/alsa-dispatcher.lsp_
  67 via a pipe (that is where *alsa-dispatcher.lsp* is for this example),
  68 and the "dispatch" PCM capture stream is sourced from _plughw_ (i.e.
  69 the default sound card).
  70
  71 Note that the playback PCM explicitly declares the stream
  72 characteristica (format, channels and rate) used up by
  73 *alsa-dispatcher.lsp*.
  74
  75 === About $HOME/.alsa-dispatcher
  76
  77 The endpoints are enumerated for *alsa-dispatcher.lsp* in a text file
  78 _$HOME/.alsa-dispatcher_ with one line for each PCM device. The line
  79 contains PCM name and optionally setting variations for that device,
  80 in the form of _key=value_. Currently only _latency_ may be varied.
  81
  82 Blank lines and lines starting with "#" are comments. The following is
  83 an illustration example.
  84
  85 ----
  86 bt
  87 usb
  88 plughw
  89 ----
  90
  91 The example _$HOME/.alsa-dispatcher_ nominates _bt_ as the first ALSA
  92 PCM to try, then the _usb_ device and the _plughw_ as the third and
  93 last option. It's an imagined setup with a bluetooth device _bt_ that
  94 should have priority when in use, next a USB sound card _usb_ as
  95 secondary option when in use, and thirdly the default sound card
  96 _plughw_.
  97
  98 Thus, *alsa-dispatcher.lsp* will try to direct playback to _bt_ first.
  99 If that is not in use *alsa-dispatcher.lsp* tries to direct playback
 100 to _usb_ and if the is not in use either, then *alsa-dispatcher.lsp*
 101 directs playback to _plughw_ (i.e. the default sound card).
 102
 103 == NOTES
 104
 105 *alsa-dispatcher.lsp* keeps playback channeling to a selected endpoint
 106 as long as that is available. If the endpoint goes away, or the
 107 *alsa-dispatcher.lsp* program is killed, that channeling is
 108 interrupted. Then the original sound source (eg a browser) may
 109 establish a new playback sink, which would caue a new
 110 *alsa-dispatcher.lsp* to run through the priority list again to pick
 111 the first option available in the then current audio context.
 112
 113 == SEE ALSO
 114
 115 *newlisp*
 116
 117 == AUTHOR
 118
 119 Ralph Ronnquist <ralph.ronnquist@gmail.com>