added README

diff --git a/Makefile b/Makefile
index 9d91011aca52da11dfccd379ad44f4ee3fe95b8d..c7c0a0044690049e68fed827f6351022e79106bf 100644 (file)
--- 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 (file)
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.
+