# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1715370629 0
# Node ID b094bc07051a1c360a3ba23c75e87cebb2e32785
# Parent  e26b974f7ba3da02cf114084d466c94e39b8aed9
doc/Codec-utils: document twamr-* addition

diff -r e26b974f7ba3 -r b094bc07051a doc/Codec-utils
--- a/doc/Codec-utils	Fri May 10 18:45:36 2024 +0000
+++ b/doc/Codec-utils	Fri May 10 19:50:29 2024 +0000
@@ -65,3 +65,63 @@
   This utility emits "robe" output like gsmfr-decode-r, but it performs only
   "basic" GSM 06.10 decoding, without the Rx DTX preprocessor step.  BFI frame
   gaps in input are not allowed, and there is no SID detection.
+
+Standalone command line utilities for AMR codec
+===============================================
+
+As described above, gsm[e]fr-encode and gsm[e]fr-decode were modeled after
+amrnb-enc and amrnb-dec from opencore-amr, a piece of pre-existing FOSS.
+However, now that we have libtwamr, a Themyscira library for AMR codec that is
+designed to serve as a replacement for libopencore-amrnb in our workflows
+involving AMR, we also have our own twamr-encode and twamr-decode utilities
+that directly replace amrnb-enc and amrnb-dec.
+
+twamr-encode is a functional replacement for amrnb-enc: it reads 16-bit linear
+PCM speech input from a WAV file and writes the AMR encoder output in a .amr
+file (RFC 4867 storage format).  However, there is a difference in the command
+line structure and a small difference in operation.  The command line structure
+of twamr-encode is as follows:
+
+twamr-encode [-d] [-2] input.wav mode output.amr
+
+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 not likely to be useful in casual twamr-encode usage, but it exists
+for the sake of symmetry with twamr-tseq-enc program used for verification
+testing with the official test sequences from 3GPP.
+
+Aside from this difference in the command line structure, the small functional
+difference between amrnb-enc and twamr-encode is that libopencore-amrnb (the
+engine underlying amrnb-enc) omits the codec homing feature, whereas libtwamr
+(the engine underlying twamr-encode) implements the homing feature as a
+mandatory part of the codec definition per 3GPP specs.
+
+twamr-encode 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-decode is a more straightforward replacement for amrnb-dec, with this
+simple command line structure:
+
+twamr-decode input.amr output.wav
+
+The functional difference from amrnb-dec is once again in the codec homing
+feature: present in libtwamr and hence twamr-decode, but absent in
+libopencore-amrnb and hence amrnb-dec.
+
+Finally, for the sake of completeness and symmetry with the other supported
+codecs, the present suite includes twamr-encode-r and twamr-decode-r utilities.
+They function just like twamr-encode and twamr-decode, with the same command
+line structure, but the file format for 16-bit linear PCM speech is "robe"
+instead of WAV.