From 6701c3fe4c0a0e1120eddc5cecc7a4c7a34bc4ed Mon Sep 17 00:00:00 2001
From: Ralph Ronnquist <ralph.ronnquist@gmail.com>
Date: Mon, 1 May 2023 14:11:28 +1000
Subject: [PATCH] fixup of comments

---
 alsa-dispatcher.lsp | 59 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 46 insertions(+), 13 deletions(-)

diff --git a/alsa-dispatcher.lsp b/alsa-dispatcher.lsp
index df8863b..2439aec 100755
--- a/alsa-dispatcher.lsp
+++ b/alsa-dispatcher.lsp
@@ -1,8 +1,38 @@
 #!/usr/bin/newlisp
 
-;; This is the main script for the pcm-dispatch tool
-;; last main-arg nominates the configuration file
-
+;; This script implements dispacth of stdin via first available for
+;; ALSA pcm listed in $HOME/.alsa-dispatcher
+;;
+;; Debug testing, eg
+;; IN=/usr/share/sounds/alsa/Rear_Left.wav
+;; sox $IN -r48000 -esigned -es-b16 -c2 x.wav | ./alsa-dispatcher
+;; o.e. send audio in format [48000 Hz S16_LE stereo wav] to the program
+;;
+;; Installation requires ALSA configuration, e.g. in ~/.asoundrc, like
+;; (replace $PROGRAM with the program's full pathname)
+;; ----
+;; pcm.dispatch {
+;;     type asym
+;;     playback {
+;;         pcm {
+;;             type plug
+;;             slave {
+;;     	           pcm "file:|exec $PROGRAM"
+;;                 format S16_LE; channels 2; rate 48000
+;;             }
+;;         }
+;;     }
+;;     capture plughw
+;; }
+;; ----
+;; $ aplav -D dispatch /usr/share/sounds/alsa/Rear_Left.wav
+;;
+;; Maybe setup "dispatch" as default
+;; ----
+;; pcm.!default dispatch
+;; ----
+
+(constant 'DEBUG nil) ;; Set to true to get stdout/stderr while degugging
 ; ############################################################
 ; misc API
 (signal 1 (fn (x) (exit 0)))
@@ -38,13 +68,14 @@
  )
 
 ; Return value of configuration setting KEY for plug PCM, or DEFAULT.
+; Only"latency=N" is possible; default 100000 (microseconds).
 (define (cfg-lookup PCM KEY DEFAULT)
   (if (if (assoc PCM CFGMAP) (lookup KEY $it)) (read-expr $it) DEFAULT))
 
 ; ############################################################
 ; libc API
-(constant 'libc.so.6 "/lib/x86_64-linux-gnu/libc.so.6")
 ; https://www.gnu.org/software/libc/manual/html_mono/libc.html
+(constant 'libc.so.6 "/lib/x86_64-linux-gnu/libc.so.6")
 
 ;; (dup2 OLDFD NEWFD) - Duplicate file descriptor OLDFD onto NEWFD,
 ;; closing the latter first if open.
@@ -55,11 +86,11 @@
 
 ; ############################################################
 ; libasound API
-(constant 'libasound.so "/usr/lib/x86_64-linux-gnu/libasound.so")
 ; https://www.alsa-project.org/alsa-doc/alsa-lib/
 ; /usr/include/asm-generic/errno-base.h
+(constant 'libasound.so "/usr/lib/x86_64-linux-gnu/libasound.so")
 
-;; Used constants
+;; Selected libasound constants
 (constant
  'SND_PCM_STREAM_PLAYBACK 0
  'SND_PCM_MODE_BLOCK 0 ; this mode label is invented here
@@ -67,22 +98,24 @@
  'SND_PCM_ACCESS_RW_INTERLEAVED 3
  )
 
-;; (snd_pcm_close PCM) - Close PCM handle. Closes the given PCM handle
-;; and frees all associated resources.
+;; (snd_pcm_close PCM) - Close PCM. Closes the given PCM and frees all
+;; associated resources.
 (import libasound.so "snd_pcm_close" "int"
         "void*" ; snd_pcm_t *pcm
         )
 
 ;; (snd_pcm_drain PCM) - Stop PCM whilst preserving pending frames.
-;; For playback wait for all pending frames to be played and then stop
-;; the PCM. For capture stop PCM permitting to retrieve residual
+;; For playback: wait for all pending frames to be played and then
+;; stop the PCM. For capture: stop PCM permitting to retrieve residual
 ;; frames.
 (import libasound.so "snd_pcm_drain" "int"
         "void*" ; snd_pcm_t *pcm
         )
 
 ;; (snd_pcm_open NAME STREAM MODE) - Opens a PCM and returns its
-;; handle or nil. Actual error code is discarded.
+;; address or nil. Any actual error code is discarded.
+; Need wrapping so as to provide a memory slot for the returned PCM
+; address. Newlisp doesn't support call-by-reference parameters well.
 (letex ((IMP (import libasound.so "snd_pcm_open" "int"
                      "void*" ; snd_pcm_t **pcmp [output]
                      "char*" ; const char *name
@@ -95,7 +128,7 @@
        (when (= (IMP PCM NAME STREAM MODE)) ((unpack "Lu" PCM) 0))))))
 
 ;; (snd_pcm_set_params PCM FMT ACCESS CH RATE RESAMPLE LATENCY) - Set
-;; the hardware and software parameters in a simple way.
+;; hardware and software parameters in a simple way.
 (import libasound.so "snd_pcm_set_params" "int"
         "void*" ; snd_pcm_t *pcm
         "int"   ; snd_pcm_format_t format
@@ -133,7 +166,7 @@
 ; The main program
 
 ; redirect stdout/err to /dev/null (flagged for debugging purposes)
-(when true
+(when (not DEBUG)
   (let ((REDIR (open "/dev/null" "append")))
     (when (< REDIR) (exit 1))
     (when (< (dup2 REDIR 2)) (exit 1))
-- 
2.39.2