Documentation added.

2026-06-08 13:16:21 +02:00
parent 8e8b9a00c0
commit 5eefacacba
7 changed files with 610 additions and 35 deletions
@@ -0,0 +1,91 @@
+#lang scribble/manual
+
+@(require (for-label racket/base
+                     racket/path
+                     "../encoder-test.rkt"))
+
+@title{Encoder Test Program}
+@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
+
+@defmodule[racket-audio/encoder-test]
+
+The @racketmodname[racket-audio/encoder-test] module is a small integration test
+and command-line wrapper around @racketmodname[racket-audio/audio-encoder].  It
+is useful for checking that the native encoder libraries are available and that
+a concrete source file can be transcoded to Opus or FLAC.
+
+The module depends on @filepath{tests.rkt} for its default input file.  For
+portable tests, pass an explicit input file.
+
+@section{Program use}
+
+Run the test module directly to encode the default test file to a temporary
+Opus file:
+
+@verbatim{
+racket encoder-test.rkt
+}
+
+Useful command-line examples:
+
+@verbatim{
+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 --bits-per-sample 24 --compression-level 8
+}
+
+The program prints the selected encoder, settings, percentage progress, and a
+summary of the result hash returned by @racket[audio-encode].  Progress is based
+on input frames read from the decoder.
+
+@section{Program options}
+
+The command-line wrapper accepts these options:
+
+@itemlist[#:style 'compact
+ @item{@tt{-e}, @tt{--encoder}: @tt{opus} or @tt{flac}.}
+ @item{@tt{-i}, @tt{--input}: input audio file.}
+ @item{@tt{-o}, @tt{--output}: output audio file.}
+ @item{@tt{--sample-rate}: target sample rate or @tt{source}.}
+ @item{@tt{--bits-per-sample}: target FLAC bit depth or @tt{source}.}
+ @item{@tt{--bitrate-kbps}: Opus bitrate in kbit/s.}
+ @item{@tt{--compression-level}: FLAC compression level.}
+ @item{@tt{--no-tags}: disable copying tags and embedded pictures.}]
+
+@section{Racket functions}
+
+@defproc[(encoder-test [input-file path-string?]
+                       [output-file (or/c path-string? #f)]
+                       [encoder (or/c symbol? string?)]
+                       [settings hash?]
+                       [#:copy-tags? copy-tags? boolean? #t])
+         hash?]{
+Runs one encode test and prints a human-readable summary.  The return value is
+the result hash produced by @racket[audio-encode].  When @racket[output-file] is
+@racket[#f], a temporary output path is chosen from the encoder kind.}
+
+@defproc[(encoder-test-opus [input-file path-string?]
+                            [output-file (or/c path-string? #f) #f]
+                            [#:bitrate-kbps bitrate-kbps exact-positive-integer? 160]
+                            [#:sample-rate sample-rate (or/c exact-positive-integer? 'source) 'source]
+                            [#:copy-tags? copy-tags? boolean? #t])
+         hash?]{
+Encodes @racket[input-file] to an Opus file using @racket[encoder-test].  The
+bitrate argument is expressed in kbit/s and is converted to the @racket['bitrate]
+setting used by the Opus backend.
+
+The @racket[sample-rate] argument is normally @racket['source].  Opus encoding
+passes the input rate to @tt{libopusenc}; @tt{libopusenc} performs the internal
+resampling required for Opus output.}
+
+@defproc[(encoder-test-flac [input-file path-string?]
+                            [output-file (or/c path-string? #f) #f]
+                            [#:compression-level compression-level exact-nonnegative-integer? 8]
+                            [#:sample-rate sample-rate (or/c exact-positive-integer? 'source) 'source]
+                            [#:bits-per-sample bits-per-sample (or/c exact-positive-integer? 'source) 'source]
+                            [#:copy-tags? copy-tags? boolean? #t])
+         hash?]{
+Encodes @racket[input-file] to a FLAC file using @racket[encoder-test].  When
+@racket[sample-rate] or @racket[bits-per-sample] is not @racket['source], the
+FLAC pipeline requests the corresponding output format from
+@racketmodname[racket-audio/audio-encoder].}