Remote usage of audio-placed-player.rkt

README.md

@@ -29,6 +29,26 @@ uses libFLAC directly.  FLAC sample-rate conversion uses the existing FFmpeg
 swresample layer.  Metadata and cover-art copying use the TagLib wrapper; the
 public `taglib.rkt` API also supports read-write tag editing.
 
+
+## Debian / Ubuntu
+
+On Debian-like systems, install the runtime and development packages for the
+selected backends.  A typical full setup is:
+
+```sh
+sudo apt install \
+  libao-dev \
+  libflac-dev \
+  libmpg123-dev \
+  ffmpeg \
+  libavutil-dev libavcodec-dev libavformat-dev libswresample-dev \
+  libogg-dev libopus-dev libopusenc-dev libopusfile-dev \
+  libtag1-dev
+```
+
+For Opus encoding, `libopusenc-dev` is required.  For Opus decoding through
+`opusfile-decoder.rkt`, install `libopusfile-dev` as well.
+
 ## macOS
 
 Using Homebrew, install the native libraries before using the package:
@@ -46,6 +66,19 @@ brew install taglib
 Some Homebrew installations provide FFmpeg as `ffmpeg`; older local setups may
 use `ffmpeg-full`.
 
+
+## Windows
+
+On Windows, the package downloader fetches the native DLL bundle from the
+Codeberg `racket-sound-lib` release area.  The current bundle URL pattern is:
+
+```text
+https://codeberg.org/hnmdijkema/racket-sound-lib/releases/download/1-1-1/windows-x86_64.zip
+```
+
+The archive is installed below Racket's addon directory by
+`download-soundlibs`.
+
 ## Encoder examples
 
 Encode to Opus:
@@ -78,3 +111,61 @@ A small test wrapper is available in `encoder-test.rkt`:
 racket encoder-test.rkt --encoder opus --input input.flac --output output.opus --bitrate-kbps 224
 racket encoder-test.rkt --encoder flac --input input-96k.flac --output output-48k.flac --sample-rate 48000
 ```
+
+## Placed player stdio mode
+
+The placed player can also run as a standard-port worker.  In that mode the
+three existing logical channels are mapped to standard streams:
+
+```text
+stdin   command channel
+stdout  reply channel
+stderr  event channel
+```
+
+Because stdout and stderr are protocol streams in this mode, ordinary display
+and log output is redirected.  By default, `placed-player/stdio` appends such
+output to a log file below Racket's standard cache directory, for example
+`~/.cache/racket/racket-audio/placed-audio-player-stdio.log` on many Unix-like
+systems.  Pass `#:log-file #f` to discard ordinary output, or pass a path to
+choose a different log file.
+
+## Remote placed player over SSH
+
+The placed player can also be started as a remote subprocess over SSH.  In this
+mode the existing three logical player channels are kept separate:
+
+```text
+stdin   command channel
+stdout  reply channel
+stderr  event channel
+```
+
+The remote worker is normally started as:
+
+```sh
+racket -l racket-audio/audio-placed-player -- --stdio
+```
+
+The worker redirects ordinary logging to a cache log file so that stdout and
+stderr remain serialized protocol streams.  On Unix-like systems the SSH
+launcher defaults to `ssh -T -q`.  On Windows it prefers PuTTY `plink.exe` or
+`plink` with `-batch -T`, and falls back to OpenSSH `ssh.exe`/`ssh` when PuTTY
+is not present.  These defaults can be overridden with the `#:ssh-program`,
+`#:ssh-options`, `#:remote-racket`, `#:remote-module`, and `#:remote-command`
+arguments to `make-audio-player`.
+
+Example:
+
+```racket
+(define player
+  (make-audio-player cb-state cb-eof
+                     #:remote-host "nas"
+                     #:remote-path-map
+                     (list (list "/muziek" "/volume1/music"))))
+
+(audio-play! player "/muziek/klassiek/track.flac")
+```
+
+The remote host must be able to read the translated path.  In the example above,
+the remote worker receives `/volume1/music/klassiek/track.flac`.