Remote usage of audio-placed-player.rkt

scrbl/audio-player.scrbl

@@ -28,7 +28,14 @@ through callbacks supplied when the player is created.
 @defproc[(make-audio-player
           [cb-state procedure?]
           [cb-eof-stream procedure?]
-          [#:use-place use-place boolean?])
+          [#:use-place use-place boolean?]
+          [#:remote-host remote-host (or/c #f string?) #f]
+          [#:remote-path-map remote-path-map any/c '()]
+          [#:remote-racket remote-racket path-string? "racket"]
+          [#:remote-module remote-module string? "racket-audio/audio-placed-player"]
+          [#:remote-command remote-command (or/c #f (listof string?)) #f]
+          [#:ssh-program ssh-program path-string? (current-racket-sound-ssh-program)]
+          [#:ssh-options ssh-options (or/c #f (listof string?)) #f])
          audio-play?]{
 Creates an audio player and returns a player handle.  The handle is passed to
 all other procedures in this module.
@@ -108,8 +115,87 @@ a separate Racket VM, so decoding and buffer feeding are less exposed to
 scheduling delays caused by DrRacket, GUI event handling, debugging, logging, or
 other active threads in the main VM.  Those delays can otherwise be heard as
 clicks, gaps, or stuttering playback.  Thread mode is useful for debugging the
-protocol and callbacks, but it is not the preferred mode for robust playback.}
+protocol and callbacks, but it is not the preferred mode for robust playback.
 
+When @racket[remote-host] is a string, @racket[make-audio-player] starts the
+worker over SSH instead of starting a local place or thread.  The remote worker
+is expected to run @racket[placed-player/stdio], where stdin is the command
+channel, stdout is the reply channel, and stderr is the event channel.  The
+client side wraps those three process ports through @racketmodname[port-channel]
+and @racketmodname[uni-channel].  The default command is equivalent to:
+
+@racketblock[
+(list remote-racket "-l" remote-module "--" "--stdio")]
+
+The remote launcher defaults are supplied by the remote utility layer.  On Unix-like systems @racket[ssh] is used with @racket['("-T" "-q")].  On Windows the launcher first looks for PuTTY @tt{plink.exe} or @tt{plink}; if found, the default options are @racket['("-batch" "-T")].  If @tt{plink} is not found, the launcher falls back to OpenSSH @tt{ssh.exe}/@tt{ssh}.  The default remote command is equivalent to:
+
+@racketblock[
+(racket-sound-default-remote-command remote-racket remote-module)]
+
+When @racket[ssh-options] is @racket[#f], suitable options are derived from the selected SSH program.  If the remote setup needs a different launcher command, provide @racket[remote-command] as a list of command-line words.
+
+The remote player must be able to open the requested audio files.  When the
+local and remote file trees differ, use @racket[remote-path-map].  It may be a
+procedure from path string to path string, or a list of mappings.  Each mapping
+may be a two-element list, a cons pair, or a two-element vector.  The longest
+matching local prefix is replaced by the corresponding remote prefix before the
+@racket['open] command is sent.  For example:
+
+@racketblock[
+(make-audio-player cb-state cb-eof
+                   #:remote-host "nas"
+                   #:remote-path-map
+                   (list (list "/muziek" "/volume1/music")))]
+
+With that mapping, @filepath{/muziek/klassiek/x.flac} is sent to the remote
+worker as @filepath{/volume1/music/klassiek/x.flac}.}
+
+
+@defproc[(audio-remote-path [path path-string?]
+                            [remote-path-map any/c])
+         string?]{
+Applies the same path translation used by remote playback.  This is primarily a
+small helper for testing SSH path-map configuration before starting playback.}
+
+
+@section[#:tag "audio-player-remote-defaults"]{Remote defaults}
+
+@defproc[(racket-sound-default-ssh-program) path-string?]{
+Returns the default SSH client for remote playback.  On Windows this prefers
+PuTTY @tt{plink.exe}/@tt{plink}, then OpenSSH @tt{ssh.exe}/@tt{ssh}.  On other
+platforms it uses @tt{ssh}.}
+
+@defproc[(racket-sound-default-ssh-options [ssh-program path-string?])
+         (listof string?)]{
+Returns default command-line options for @racket[ssh-program].  For @tt{plink}
+this is @racket['("-batch" "-T")]; for OpenSSH this is @racket['("-T" "-q")].}
+
+@defproc[(racket-sound-default-remote-racket) string?]{
+Returns the default remote Racket executable name, currently @racket["racket"].}
+
+@defproc[(racket-sound-default-remote-module) string?]{
+Returns the default remote module, currently
+@racket["racket-audio/audio-placed-player"].}
+
+@defproc[(racket-sound-default-remote-command
+          [remote-racket path-string? (racket-sound-default-remote-racket)]
+          [remote-module string? (racket-sound-default-remote-module)])
+         (listof string?)]{
+Builds the default remote worker command:
+
+@racketblock[
+(list remote-racket "-l" remote-module "--" "--stdio")]
+}
+
+@defthing[current-racket-sound-ssh-program parameter?]{
+Parameter holding the default SSH program used by @racket[make-audio-player]
+when @racket[#:ssh-program] is not supplied.}
+
+@defthing[current-racket-sound-remote-racket parameter?]{
+Parameter holding the default remote Racket executable name.}
+
+@defthing[current-racket-sound-remote-module parameter?]{
+Parameter holding the default remote module name.}
 
 @defproc[(audio-play? [v any/c]) boolean?]{
 Returns @racket[#t] when @racket[v] is a currently valid audio player handle.