From 912b5de1e53e55b31357bf5366fa6cd236e44547 Mon Sep 17 00:00:00 2001
From: Ralph Ronnquist <ralph.ronnquist@gmail.com>
Date: Sun, 30 Apr 2023 13:26:38 +1000
Subject: [PATCH] added README

---
 Makefile    |  5 ++++-
 README.adoc | 30 ++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100644 README.adoc

diff --git a/Makefile b/Makefile
index 9d91011..c7c0a00 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,5 @@
 # Local building
-default: alsa-dispatcher.8.gz alsa-dispatcher 
+default: alsa-dispatcher.8.gz alsa-dispatcher README.html
 
 ALSACONF = $(DESTDIR)/etc/alsa/conf.d/51-dispatcher.conf
 
@@ -13,6 +13,9 @@ ALSACONF = $(DESTDIR)/etc/alsa/conf.d/51-dispatcher.conf
 $(HOME)/.asoundrc: example.alsa.conf
 	grep -q ^pcm.dispatch $@ || cat $< >> $@
 
+README.html: README.adoc
+	asciidoctor -o $@ $< 
+
 clean::
 	rm -f alsa-dispatcher alsa-dispatcher.8.gz
 
diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..7115c83
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,30 @@
+= alsa-dispatcher
+
+This project implements a dispatch function for ALSA playback for
+dynamic selection of output device. The idea is to direct playback
+when it starts to the first output from the user's priority list that
+is available at that time.
+
+For instances, you might have three different output devices sometimes
+available:
+
+  1. a bluetooth headset
+  2. a USB soundcard for wall speakers, and
+  3. a built-in soundcard for desktop speakers.
+
+and want them to selected in that priority order. I.e. playback should
+be directed to the bluetooth headset, if connected; otherwise to the
+USB soundcard, if plugged in; and otherwise to the built-in soundcard.
+
+Ordinarily it will take some editing of ~/.asoundrc to explicitly
+select output device for a program before it starts, and them that
+program will keep using that setup onwards.
+
+*alsa-dispatcher* provides that dynamic selection based on the user's
+priority list without need of editing or playback program restart. By
+this solution, there is a dynamic link in the playback chain that
+applies the dispatch logic whenever a program starts playback anew.
+Thus, the output device is decided depending on what is available when
+the playback starts, or more specifically whenever a program opens an
+output sink to start or to continue playback.
+
-- 
2.39.2