#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].}