# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1716166957 0
# Node ID cc0c244bd23336fbcc379efd1a5da01f02db4ae5
# Parent  332397bc80aa058eab66cc197b0272767619a47a
doc/AMR-library-tests: new article

diff -r 332397bc80aa -r cc0c244bd233 doc/AMR-library-tests
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/AMR-library-tests	Mon May 20 01:02:37 2024 +0000
@@ -0,0 +1,59 @@
+The present suite includes a pair of command line programs that exercise
+libtwamr encoder and decoder in 3GPP test sequence format, allowing this library
+to be tested against the official test sequences of 3GPP TS 26.074.
+
+twamr-tseq-enc
+==============
+
+This program reads a *.inp file from the collection of TS 26.074, encodes it
+per selected AMR mode using libtwamr functions, and emits the encoder output in
+3GPP-defined .cod format.  The command line structure of twamr-tseq-enc is as
+follows:
+
+twamr-tseq-enc [-d] [-2] input.inp mode output.cod
+
+The middle argument specifies the codec mode to be used; there is no default.
+Ordinarily the mode argument is one of these 8 keywords:
+
+	MR475
+	MR515
+	MR59
+	MR67
+	MR74
+	MR795
+	MR102
+	MR122
+
+However, this mode argument can also take the form of "file:$modefile", where
+$modefile is an ASCII text file giving one of the above mode keywords per line.
+This form is needed when testing the encoding of t21.inp per t21.mod control
+file.
+
+twamr-tseq-enc flag options: -d enables DTX, -2 switches the VAD algorithm from
+VAD1 default to VAD2 alternative.  The two options can be combined as -d2.
+
+twamr-tseq-dec
+==============
+
+This program reads a *.cod file in 3GPP AMR test sequence format, decodes it
+using libtwamr functions, and emits the decoder output in a raw PCM *.out file.
+The command line structure of twamr-tseq-dec is as follows:
+
+twamr-tseq-dec [-r] input.cod output.out
+
+By default the first word of each *.cod frame is expected to be a Tx frame type
+as in enum TXFrameType; with -r option this first word is expected to be an Rx
+frame type as in enum RXFrameType instead.  This option directly corresponds to
+-rxframetype in the reference decoder program from 3GPP.
+
+Byte order considerations
+=========================
+
+Both twamr-tseq-enc and twamr-tseq-dec read and write their input and output
+files (16-bit linear PCM on one end and 3GPP *.cod test sequence format on the
+other end) in the local machine's native byte order.  3GPP shipped their
+TS 26.074 collection of AMR test sequences in little-endian byte order; given
+that most GSM software developers are now largely forced by economic pressures
+to work on x86 or ARM architecture machines rather than more noble SPARC or
+PowerPC systems, the local byte order of the developer's machine will typically
+be LE, matching TS 26.074 files as published.