--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Codec-utils	Sun Dec 11 22:20:36 2022 +0000
@@ -0,0 +1,39 @@
+Standalone command line utilities for FR and EFR codecs
+=======================================================
+
+The pre-existing FOSS opencore-amr package includes amrnb-enc and amrnb-dec test
+programs: the first reads linear PCM from a WAV file and emits AMR encoder
+output in a .amr file (RFC 4867 AMR storage format), the second reads this .amr
+format and emits AMR decoder output as WAV.  Inspired by these simple test
+programs, the present package offers equivalent command line utilities for GSM
+FR and EFR codecs.  Here they are:
+
+gsmfr-encode	This utility reads linear PCM from a WAV file, runs libgsm
+		06.10 encoder and writes the output in the classic .gsm format
+		(directly abutted FR codec frames of 33 bytes each).  We don't
+		currently have a Tx-side DTX implementation (VAD etc) for GSM
+		FR, hence the output from gsmfr-encode will always consist of
+		good speech frames only.
+
+gsmfr-decode	This utility reads our gsmx format (see Binary-file-format
+		article), which is a superset of the classic libgsm format.
+		The input to gsmfr-decode may be a pure .gsm recording as
+		produced by gsmfr-encode or toast from libgsm package, or it
+		can also contain SID frames and/or BFI markers.  The processing
+		performed by gsmfr-decode begins with our FR1 Rx DTX handler
+		preprocessor, which will be an identity transform for pure .gsm
+		input but becomes important for real-world input containing SIDs
+		and BFIs, and is followed by gsm_decode() from libgsm.  The
+		decoded output is written as WAV.
+
+gsmefr-encode	This utility reads linear PCM from a WAV file, runs our EFR
+		encoder (Themyscira libgsmefr) and writes the output in our gsmx
+		format.  There is an option to enable or disable DTX: -d enables
+		DTX, otherwise it is disabled.  (This option mirrors amrnb-enc.)
+
+gsmefr-decode	This utility reads our gsmx format (which must be EFR, not FR1)
+		and feeds all frames and BFIs to our EFR decoder.  The decoded
+		output is written as WAV.
+
+WAV reading and writing functions used by the above utilities have been lifted
+out of opencore-amrnb test code.