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 temporarily
   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 == CONFIGURATIONS
  27
  28 The setup for using *alsa-dispatcher.lsp* includes two configuration
  29 aspects:
  30
  31  1. The ALSA configuration collection needs to be augmented with a
  32  _pcm_ block that directs playback to *alsa-dispatcher.lsp* and
  33  capture from, say, _plughw_ (i.e., the primary sound card).
  34
  35  2. The priority list of posible endpoints for *alsa-dispatcher.lsp*
  36  is a text file named _$HOME/.alsa-dispatcher_.
  37
  38 []
  39
  40 *ALSA configuration (e.g. $HOME/.asoundrc)*::
  41
  42 The ALSA configuration collection needs to include a declaration for
  43 *alsa-dispatcher* as an ALSA PCM by means of a short declaration in
  44 the user's _$HOME/.asoundrc_ file or system-wide in
  45 _/etc/asoundrc.conf_ The following is an example _$HOME/.asoundrc_.
  46 +
  47 ----
  48 pcm.!default dispatch
  49
  50 pcm.dispatch {
  51     type asym
  52     playback {
  53         pcm "file:|exec /usr/local/bin/alsa-dispatcher.lsp"
  54     }
  55     capture plughw
  56 }
  57 ----
  58 +
  59 The first line in the example asserts that "dispatch" is the default
  60 PCM.
  61 +
  62 The lines below that declares the "dispatch" PCM to have its playback
  63 stream directed to the command _/usr/local/bin/alsa-dispatcher.lsp_
  64 via a pipe (that is where *alsa-dispatcher.lsp* is for this example),
  65 and the "dispatch" PCM capture stream is sourced from _plughw_ (i.e.
  66 the default sound card).
  67
  68 *About $HOME/.alsa-dispatcher*::
  69
  70 Possible endpoints are enumerated for *alsa-dispatcher.lsp* in a text
  71 file _$HOME/.alsa-dispatcher_ with one line for each PCM device. The
  72 line contains its name and optionally some specific setting variation
  73 for that device. Such settings have the form of _key=value_ with space
  74 seapartion between settings. Blank lines and lines starting with "#"
  75 are comments. The following is an illustration example.
  76 +
  77 ----
  78 bt
  79 plughw
  80 ----
  81 +
  82 The example _$HOME/.alsa-dispatcher_ nominates _bt_ as the first ALSA
  83 PCM to try, and _plughw_ as the second (and last). This illustrates
  84 ain imagined setup with a bluetooth device _bt_ that should have
  85 priority when in use. *alsa-dispatcher.lsp* will direct playback to
  86 _bt_ if it is in use and otherwise fall back on _plughw_ (i.e. the
  87 default sound card).
  88
  89 == SEE ALSO
  90
  91 *newlisp*
  92
  93 == AUTHOR
  94
  95 Ralph Ronnquist <ralph.ronnquist@gmail.com>