--- a/doc/AMR-EFR-philosophy	Fri May 10 07:35:36 2024 +0000
+++ b/doc/AMR-EFR-philosophy	Fri May 10 18:20:06 2024 +0000
@@ -48,42 +48,54 @@
 I (Mother Mychaela) previously entertained the idea of creating a unified codec
 library that supports both AMR and EFR with common code, producing a published-
 source, FOSS-culture equivalent of what most proprietary vendors have done.
-However, on further reflection, that idea has been rejected.  The current vision
-(as of 2024-04) is that libgsmefr (stable since early 2023) and libtwamr
-(currently a work in progress) shall remain separate and independent libraries,
-the former implementing GSM-EFR (the original bit-exact definition) and the
-latter implementing AMR.  My reasons for this decision are:
+However, on further reflection, that idea has been rejected.  The current
+situation as of 2024-05 is as follows:
+
+* Libgsmefr is our production-oriented implementation of GSM-EFR codec.  It
+  implements the original bit-exact definition of EFR, not the AMR-EFR hybrid
+  version, and it includes full support for DTX encoding and SID decoding with
+  comfort noise generation per GSM 06.62.
 
-* Libgsmefr already exists, and it is already a bit of a jewel compared to the
-  sorry state of true GSM codec support in the world of FOSS outside Themyscira.
-  Giving up on this library and moving to some nebulous new one does not sound
-  appealing.
-
-* There does not exist any formal, bit-exact definition for what we informally
-  call "EFR version 2": the realization of EFR as implemented by post-AMR-era
-  proprietary vendors, some sort of AMR-EFR hybrid.  As I see it, it is not my
-  place to try to innovate in speech codec design, instead it is my job to
-  provide 100% correct, bit-exact implementations of existing solid standards -
-  and there is no bit-exact standard to follow for "EFR version 2".
+* Libtwamr is our librification of 3GPP AMR reference code.  The library is
+  structured in such a way that libtwamr stateful encoder and decoder functions
+  can be combined with stateless EFR frame packing and unpacking functions from
+  libgsmefr, allowing AMR-EFR hybrid encoders and decoders to be built.  The
+  decoder homing function in libtwamr can be told to trigger on EFR DHF instead
+  of MR122 version, and for the encoder direction there is a simple utility
+  function that artificially transforms MR122 DHF into EFR DHF post-encoder.
+  However, there is no support for AMR-EFR hybrid encoding with DTX enabled,
+  and the low-effort version of AMR-EFR hybrid decoder constructed in this
+  manner cannot grok EFR SID frames or generate CN per GSM 06.62.
 
-* Libtwamr project: the task of turning the original AMR code from 3GPP into a
-  proper library, style-consistent with Themyscira libgsmfr2 and libgsmefr,
-  without the ugliness of opencore-amr, is already a lot of work as it is.
-  There is no need to make it harder by adding the task of supporting AMR-based
-  EFR, especially when the latter lacks formal definition.
+Production implementations of GSM network elements that need to perform EFR
+speech transcoding should use libgsmefr, not libtwamr.  The limited support
+that is provided for AMR-EFR hybrid encoding and decoding with the combination
+of libtwamr and libgsmefr is intended for experimentation and reverse
+engineering of other people's implementations, for times when it becomes
+necessary to model, simulate or replicate bit-exact operation of someone else's
+network element.
 
-Performance issues
-==================
+Command line utilities for AMR-EFR hybrid
+=========================================
+
+The present package includes a small set of command line utilities that work
+with the AMR-EFR hybrid described above:
 
-Right now the only significant downside of libgsmefr compared to
-libopencore-amrnb is that our library is significantly slower: almost 7 times
-slower on non-DTX encode and a little over 3 times slower on SID-free decode.
-However, this performance problem will need to be solved by profiling the code
-to find the slowest spots, comparing the code of individual blocks between ours
-and theirs, and porting over whatever performance-optimizing strategies were
-implemented in OpenCORE code base.  The latter code base is a derivative work
-based on 3GPP AMR source, hence the guts of the codec are largely the same
-between 3GPP AMR and libopencore-amrnb; the latter has been significantly
-performance-optimized, but also heavily uglified.  But there is no reason why
-the same performance fixes can't be applied to EFR code base - it will simply
-take work.  This work is currently part of our future roadmap.
+amrefr-encode-r
+amrefr-decode-r
+
+	These two utilities function just like gsmefr-encode-r and
+	gsmefr-decode-r described in Codec-utils article, but implement the
+	AMR-EFR hybrid version of the codec instead of original EFR.  The
+	no-DTX limitation applies: amrefr-encode-r lacks -d option, and the
+	input to amrefr-decode-r must not contain any SID frames.
+
+amrefr-tseq-enc
+amrefr-tseq-dec
+
+	These two utilities are AMR-EFR counterparts to gsmefr-etsi-enc and
+	gsmefr-etsi-dec test programs described in EFR-testing article.  They
+	pass all tests on the non-DTX t??_efr.* sequences in ETSI's
+	amr122_efr.zip, but not on any of the DTX sequences included in the
+	same ZIP.  Just like amrefr-encode-r, amrefr-tseq-enc lacks -d option,
+	and amrefr-tseq-dec rejects input containing SID frames.