From ea26a44b182377a3ac15ca4daffc60a39298dce7 Mon Sep 17 00:00:00 2001
From: Ralph Ronnquist <ralph.ronnquist@gmail.com>
Date: Fri, 28 Apr 2023 01:52:26 +1000
Subject: [PATCH] started doc

---
 alsa-dispatcher.8.adoc | 93 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 alsa-dispatcher.8.adoc

diff --git a/alsa-dispatcher.8.adoc b/alsa-dispatcher.8.adoc
new file mode 100644
index 0000000..0e27fc9
--- /dev/null
+++ b/alsa-dispatcher.8.adoc
@@ -0,0 +1,93 @@
+= alsa-dispatcher(8)
+:doctype: manpage
+:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+
+== NAME
+
+alsa-dispatcher - ALSA playback priority dispatcher for temporarily
+connected playback endpoints.
+
+== SYNOPSIS
+
+*alsa-dispatcher.lsp*
+
+== 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
+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 system setup for using *alsa-dispatcher.lsp* 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).
+
+ 2. The priority list for *alsa-dispatcher.lsp* of posible endpoints
+ is a text file named _$HOME/.alsa-dispatcher_.
+
+[]
+
+*ALSA configuration (e.g. $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"
+    }
+    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.
++
+----
+bt
+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).
+
+== SEE ALSO
+
+*newlisp*
+
+== AUTHOR
+
+Ralph Ronnquist <ralph.ronnquist@gmail.com>
-- 
2.39.2