X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=alsa-dispatcher.8.adoc;h=3261edbb2fda003ac1b7595e7fd4c2ec5ca09dbb;hb=fbe8cc7a18a4f075cb6784a9dc706e279a40c2b0;hp=64e8227d39722bc68edfd7c635a91e0239369f66;hpb=462ec06035c059c3a5d74019317ae4db94d32678;p=rrq%2Fnewlisp%2Falsa-dispatcher.git diff --git a/alsa-dispatcher.8.adoc b/alsa-dispatcher.8.adoc index 64e8227..3261edb 100644 --- a/alsa-dispatcher.8.adoc +++ b/alsa-dispatcher.8.adoc @@ -4,87 +4,113 @@ == NAME -alsa-dispatcher - ALSA playback priority dispatcher for temporarily -connected playback endpoints. +alsa-dispatcher - ALSA priority dispatcher for occasional playback +endpoints. == SYNOPSIS -*alsa-dispatcher.lsp* +*alsa-dispatcher* == 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 +*alsa-dispatcher* 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* 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 +The setup for using *alsa-dispatcher* 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). + 1. The ALSA configuration needs to be augmented with a _pcm_ block + that directs playback to *alsa-dispatcher* and capture from, say, + _plughw_ (i.e., the primary sound card). - 2. The priority list of posible endpoints for *alsa-dispatcher.lsp* + 2. The priority list of possible endpoints for *alsa-dispatcher* is a text file named _$HOME/.alsa-dispatcher_. -[] - -*ALSA configuration (e.g. $HOME/.asoundrc)*:: +=== 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_. -+ +the user's _$HOME/.asoundrc_ file or system-wide (e.g +_/etc/asoundrc.conf_ or _/etc/alsa/conf.d/51-alsa-dispatcher.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" + pcm { + type plug + slave { + pcm "file:|exec /usr/bin/alsa-dispatcher" + format S16_LE; channels 2; rate 48000; + } + } } 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. -+ +PCM. I.e. that playback directed to "default" should be passed on to +"dispatch". + +The rest of the example declares the "dispatch" PCM to be an "asym" +that has the playback stream directed via a pipe to the command +_/usr/bin/alsa-dispatcher_ (which is where *alsa-dispatcher* is +installed in this example), and further it has the capture stream +sourced from _plughw_ (i.e. the default sound card). + +Note that the playback PCM explicitly declares the stream +characteristics (format, channels and rate) as used by +*alsa-dispatcher*. + +=== About $HOME/.alsa-dispatcher + +The endpoints are enumerated for *alsa-dispatcher* 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, 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). +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 third the default sound card +_plughw_. + +Thus, *alsa-dispatcher* will try to direct playback to _bt_ first. If +that is not in use *alsa-dispatcher* tries to direct playback to _usb_ +and if the is not in use either, then *alsa-dispatcher* directs +playback to _plughw_ (i.e. the default sound card). + +== NOTES + +*alsa-dispatcher* keeps channeling playback to a selected endpoint as +long as that remains available. If the endpoint goes away (or the +*alsa-dispatcher* program is killed) that channeling is interrupted. +The original sound source (eg a browser) may then establish a new +playback sink, which would cause a new *alsa-dispatcher* to run +through the priority list again to pick the first option available in +the then current audio context. + +The program is an embedded _newlisp_ script of manageable size that +links up with _libasound.so_ for ALSA API actions. == SEE ALSO