# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1682120516 0
# Node ID f4f68c652e98092a3f5279802a5c1eef1e89bf39
# Parent  1a7d659a952f6429a43231736121928ce8a556bc
doc: document AMR study utilities

diff -r 1a7d659a952f -r f4f68c652e98 doc/AMR-study-utils
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/AMR-study-utils	Fri Apr 21 23:41:56 2023 +0000
@@ -0,0 +1,25 @@
+As of this writing (2023-04), the main emphasis here at Themyscira Wireless is
+on classic FR and EFR codecs, particularly the latter, rather than AMR.
+However, given the close relation between GSM EFR and the highest MR122 mode of
+AMR, we are starting to explore AMR a little too, focusing on the reference C
+implementation and various published test sequences.  Working in this direction,
+we have developed the following AMR study and exploration utilities:
+
+amr-cod-parse	This utility reads the *.cod binary file format used by 3GPP
+		reference code and test sequences for AMR-encoded speech, groks
+		every frame and dumps all recorded parameters in human-readable
+		form.
+
+amr-ietf-parse	A similar AMR parse/dump utility to amr-cod-parse, but reading
+		the more common IETF RFC 4867 *.amr binary file format instead.
+
+amr-cod2ietf	These two utilities convert between 3GPP *.cod and IETF *.amr
+amr-ietf2cod	formats.  amr-cod2ietf converts from *.cod to *.amr;
+		amr-ietf2cod converts in the opposite direction.
+
+Just like ETSI *.cod and *.dec formats for EFR, 3GPP *.cod format for AMR is
+endian-dependent.  Our amr-cod-parse and amr-cod2ietf utilities expect LE byte
+order by default, matching the official test sequences in
+ts_126074v170001p0.zip; they also support BE byte order with -b option.
+However, our amr-ietf2cod utility (rarely needed) emits its cod-format output
+in the local machine's native byte order.
diff -r 1a7d659a952f -r f4f68c652e98 doc/Utils-overview
--- a/doc/Utils-overview	Fri Apr 21 21:46:38 2023 +0000
+++ b/doc/Utils-overview	Fri Apr 21 23:41:56 2023 +0000
@@ -1,6 +1,11 @@
 Here is the complete list of all command line utilities included in the present
 package:
 
+amr-cod-parse		See AMR-study-utils article.
+amr-ietf-parse
+amr-cod2ietf
+amr-ietf2cod
+
 gsm-amr2efr		See AMR-EFR-conversion article.
 gsm-efr2amr