Documentation added

scrbl/racket-audio.scrbl

@@ -0,0 +1,96 @@
+#lang scribble/manual
+
+@(require racket/runtime-path
+          scribble/core
+          scribble/html-properties
+          (for-label racket/base
+                     racket/path
+                     "../audio-player.rkt"
+                     "../taglib.rkt"
+                     "../audio-sniffer.rkt"
+                     "../audio-decoder.rkt"
+                     "../audio-placed-player.rkt"
+                     "../libao.rkt"
+                     "../mp3-decoder.rkt"
+                     "../flac-decoder.rkt"
+                     "../ffmpeg-decoder.rkt"))
+
+@(define-runtime-path rktplayer-logo "rktplayer.svg")
+
+@(define title-logo-style
+   (style #f
+          (list (attributes
+                 '((style . "float: right; margin-left: 1.5em; margin-bottom: 0.5em;"))))))
+
+@elem[#:style title-logo-style]{@image[#:scale 0.25 rktplayer-logo]}
+
+@title{@elem{racket-audio}}
+
+
+@;;title{racket-audio}
+@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
+
+@racketmodname[racket-audio] is a small audio playback toolkit for Racket.  It
+combines high-level asynchronous playback, optional metadata reading, file type
+sniffing, decoder backends, and libao based output.  Most applications should
+start with the high-level player API and only use the lower-level modules when
+they need to add a decoder, inspect the playback pipeline, or debug the native
+FFI boundary.
+
+@section{APIs for normal users}
+
+For ordinary playback, use @racketmodname[racket-audio/audio-player].  It
+creates an audio player, starts the worker side, and exposes procedures such as
+@racket[make-audio-player], @racket[audio-play!], @racket[audio-pause!],
+@racket[audio-stop!], @racket[audio-seek!], and @racket[audio-quit!].  The
+player is asynchronous: commands return after they have been accepted, while
+state updates and end-of-stream notifications are delivered through callbacks.
+
+Use @racketmodname[racket-audio/taglib] when an application needs metadata such
+as title, artist, album, duration-related properties, generic TagLib properties,
+or embedded cover art.  The module reads metadata into a Racket-side snapshot
+and does not keep the native TagLib file handle open.
+
+Use @racketmodname[racket-audio/audio-sniffer] when file type detection should
+be based on file contents rather than only on extensions.  The sniffer is useful
+before choosing a decoder, validating input, or presenting a likely media type
+to the user.
+
+The @racketmodname[racket-audio/play-test] module is not a library API, but it
+is a useful integration example.  In particular, its queue mode, selected with
+@racket[(set-test 'queue)], shows how an EOF callback can start the next item
+in a simple playback queue.
+
+@section{Lower-level modules for geeks}
+
+The modules below are normally used by the player implementation rather than by
+application code.  They are documented because they are useful when extending,
+debugging, or replacing parts of the pipeline.
+
+@itemlist[#:style 'compact
+ @item{@racketmodname[racket-audio/audio-placed-player] implements the worker
+       side of the high-level player.  It is normally run in a Racket place, so
+       the timing-sensitive audio feeder runs in a separate VM, but it can also
+       be run in a thread with async channels for easier debugging.}
+ @item{@racketmodname[racket-audio/audio-decoder] provides the decoder registry
+       and a uniform open/read/seek/stop interface over concrete decoder
+       backends.}
+ @item{@racketmodname[racket-audio/mp3-decoder],
+       @racketmodname[racket-audio/flac-decoder], and
+       @racketmodname[racket-audio/ffmpeg-decoder] are concrete decoder
+       frontends.  The FFmpeg path is the general-purpose fallback for formats
+       not handled by the specialised decoders.}
+ @item{@racketmodname[racket-audio/libao] and
+       @racketmodname[racket-audio/libao-async-ffi-racket] form the output side:
+       they open the native audio device, queue PCM buffers, apply volume, and
+       feed libao asynchronously.}
+ @item{@racketmodname[racket-audio/ffmpeg-ffi],
+       @racketmodname[racket-audio/ffmpeg-definitions], and the FFmpeg C backend
+       documentation describe the native FFmpeg boundary, the direct FFI
+       definitions, version-sensitive structures, and the fixed PCM format used
+       by the decoder pipeline.}]
+
+In short: applications should usually combine
+@racketmodname[racket-audio/audio-player] with @racketmodname[racket-audio/taglib].
+The other modules document the machinery underneath: format detection, decoder
+selection, place-based playback, buffering, native output, and FFmpeg access.