Opus decoder is now documented

scrbl/audio-decoder.scrbl

@@ -2,8 +2,10 @@
 
 @(require racket/base
           (for-label racket/base
+                     racket/contract
                      racket/path
-                     "../audio-decoder.rkt"))
+                     "../audio-decoder.rkt"
+                     "../audio-sniffer.rkt"))
 
 @title{audio-decoder}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
@@ -15,9 +17,9 @@ decoders. A backend is selected from the filename extension and is then
 used through a uniform interface for opening, reading, seeking, and
 stopping.
 
-The module includes built-in readers for FLAC and MP3, and it allows
-additional backends to be registered with
-@racket[audio-register-reader!].
+The module includes built-in readers for FLAC, MP3, Opus via
+@tt{libopusfile}, and FFmpeg-backed formats. Additional backends can be
+registered with @racket[audio-register-reader!].
 
 @section{Reader registration}
 
@@ -79,8 +81,8 @@ otherwise.
 
 Returns the reader type stored in @racket[handle].
 
-For the built-in readers this is either @racket['flac] or
-@racket['mp3].
+For the built-in readers this is usually @racket['flac], @racket['mp3],
+@racket['opusfile], or @racket['ffmpeg].
 }
 
 @section{Known extensions and validation}
@@ -89,9 +91,56 @@ For the built-in readers this is either @racket['flac] or
 
 Returns the list of known filename extensions.
 
-The initial list contains @racket["flac"] and @racket["mp3"].
-Additional extensions are added when readers are registered with
-@racket[audio-register-reader!].
+The initial list contains the extensions handled by the built-in readers:
+@racket["flac"], @racket["mp3"], Opus/Ogg extensions such as
+@racket["opus"], @racket["ogg"], and @racket["oga"], and the extensions
+handled by the FFmpeg reader. Additional extensions are added when
+readers are registered with @racket[audio-register-reader!].
+}
+
+
+@defproc[(audio-supported-extensions) (listof string?)]{
+
+Returns the current list of supported filename extensions. This is the
+same list returned by @racket[audio-known-exts?].
+}
+
+@section{Built-in decoder selection}
+
+The built-in decoder table contains:
+
+@itemlist[#:style 'compact
+ @item{@racket['flac] for FLAC files;}
+ @item{@racket['mp3] for MP3 files;}
+ @item{@racket['opusfile] for Ogg Opus streams through Xiph
+       @tt{libopusfile};}
+ @item{@racket['ffmpeg] for formats handled by the FFmpeg backend.}]
+
+When a file is opened, the module first asks
+@racket[audio-sniff-format/extension] for the detected format. Opus
+streams are mapped to @racket['opusfile] when @tt{libopusfile} is
+available and to @racket['ffmpeg] otherwise.
+
+The Opusfile decoder has one global setting for its PCM output format:
+@racket[current-opusfile-output-format]. This setting is re-exported by
+this module for callers that use only the generic decoder API.
+
+@defthing[current-opusfile-output-format procedure?]{
+
+A global setting procedure for the Opusfile backend. Called without
+arguments, it returns the current Opusfile output format. Called with one
+argument, it sets the output format. Accepted values are @racket['s16]
+and @racket['s24].
+
+The default is @racket['s16]. Set it to @racket['s24] before opening or
+reading an Opus file when the playback pipeline should receive packed
+signed 24-bit PCM instead of signed 16-bit PCM.
+}
+
+@defproc[(opusfile-output-format? [v any/c]) boolean?]{
+
+Returns @racket[#t] when @racket[v] is one of the supported Opusfile
+output format symbols: @racket['s16] or @racket['s24].
 }
 
 @defproc[(audio-valid-ext? [ext any/c]) boolean?]{
@@ -146,7 +195,8 @@ where:
 
 @itemlist[#:style 'compact
  @item{@racket[audio-type] is the registered reader type, such as
-       @racket['flac] or @racket['mp3];}
+       @racket['flac], @racket['mp3], @racket['opusfile], or
+       @racket['ffmpeg];}
  @item{@racket[ao-type] is the audio-output type stored in the reader,
        such as @racket['flac] or @racket['ao];}
  @item{@racket[handle] is the generic @racket[audio-handle];}
@@ -255,5 +305,5 @@ A backend integrated through this interface should provide:
        backend produces.}]
 
 Once registered, files with matching extensions can be opened through
-@racket[audio-open] in the same way as the built-in FLAC and MP3
-backends.
+@racket[audio-open] in the same way as the built-in FLAC, MP3,
+Opusfile, and FFmpeg backends.