X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=alsa-dispatcher.8.adoc;h=43c28a9a3989ec06b754463698501c21f45d4025;hb=6ae03e28eb75607ef87994ec9823031b66a24390;hp=0e27fc9c4b73a88aadb2d7e18424c383ba062ef7;hpb=ea26a44b182377a3ac15ca4daffc60a39298dce7;p=rrq%2Fnewlisp%2Falsa-dispatcher.git diff --git a/alsa-dispatcher.8.adoc b/alsa-dispatcher.8.adoc index 0e27fc9..43c28a9 100644 --- a/alsa-dispatcher.8.adoc +++ b/alsa-dispatcher.8.adoc @@ -4,8 +4,8 @@ == NAME -alsa-dispatcher - ALSA playback priority dispatcher for temporarily -connected playback endpoints. +alsa-dispatcher - ALSA priority dispatcher for occasional playback +endpoints. == SYNOPSIS @@ -23,66 +23,92 @@ 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 +aspects: -The system 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). - 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). - - 2. The priority list for *alsa-dispatcher.lsp* of posible endpoints + 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) -*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 ALSA configuration collection needs to include setup for -*alsa-dispatcher* as an ALSA PCM by means of e.g. a short declaration -in the user's _$HOME/.asoundrc_ file, or system-wide in -_/etc/asoundrc.conf_ The following is an example. -+ ---- 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.lsp" + format S16_LE; channels 2; rate 48000; + } + } } capture plughw } ---- -+ -The first of those lines asserts that "dispatch" is the default -PCM. -+ -The lines below declares the "dispatch" PCM to have its playback -stream directed via a pipe to the command -_/usr/local/bin/alsa-dispatcher.lsp_ (assuming that is where -*alsa-dispatcher.lsp* is), and its capture stream is sourced from -_plughw_ (i.e. the default sound card). - -*About $HOME/.alsa-dispatcher*:: - -The possible endpoints are enumerated in _$HOME/.alsa-dispatcher_ with -one line for each PCM device: its name and optionally some specific -setting variation for that device in the form of _key=value_. Blank -lines and lines starting with "#" are comments. The following is an -example. -+ + +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, and then _plughw_ as the second (and last). This suggest a -bluetooth device _bt_ that has 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 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