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