--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/AMR-library-desc	Sat May 18 21:22:07 2024 +0000
@@ -0,0 +1,88 @@
+Themyscira libtwamr general description
+=======================================
+
+Libtwamr is a librification of the official AMR reference C code from 3GPP,
+produced by Themyscira Wireless and styled to match our libraries for more
+classic GSM codecs.  This library has been created with the following two goals
+in mind:
+
+1) At the present time we (ThemWi) operate our GSM network with only GSM-FR and
+   GSM-EFR codecs, with the latter being preferred.  We do not currently operate
+   with AMR because the conditions under which AMR becomes advantageous do not
+   currently exist in our network operation.  However, we need to be prepared
+   for the possibility that the conditions which make AMR desirable may arise
+   some day, and we may need to start deploying AMR.  In order to make AMR
+   deployment a possibility, many parts will need to be implemented, one of
+   which is a speech transcoding library that implements the AMR codec in the
+   same way how libgsmfr2 and libgsmefr implement the more classic codecs which
+   we use currently.
+
+2) Many other commercial GSM networks have implemented EFR speech service using
+   a type of AMR-EFR hybrid described in AMR-EFR-philosophy and
+   AMR-EFR-hybrid-emu articles.  As part of certain behavioral reverse
+   engineering experiments, we sometimes need to model the bit-exact operation
+   of those other-people-controlled commercial implementations of AMR-EFR, and
+   our current libtwamr provides one way to do so.  Knowing that a proper
+   implementation of an AMR codec library is likely to be needed some day for
+   reason 1 above, justification was obtained for expending the effort to
+   produce the present libtwamr.
+
+Compared to other plausible ways in which someone could reasonably approach the
+task of librifying the AMR reference code from 3GPP, the design of libtwamr
+includes two somewhat original choices:
+
+* Separation of core and I/O: the stateful encoder and decoder engines in
+  libtwamr operate on a custom frame structure that includes the array of codec
+  parameters in their broken-down form (e.g., 57 parameters for MR122), the
+  frame type as in original RXFrameType and TXFrameType, and the codec mode.
+  Conversion between this internal canonical form (which is most native to the
+  guts of the encoder and decoder engines) and external I/O formats (the 3GPP
+  test sequence format and the more practical RFC 4867 format used in RTP and
+  in .amr recording files) is relegated to stateless utility functions.
+
+* Both VAD1 and VAD2 included: the reference code from 3GPP includes two
+  alternative versions of Voice Activity Detection algorithm, VAD1 and VAD2.
+  Implementors are allowed to use either version and be compliant; 3GPP code
+  uses conditional compilation to select between the two, and it appears that
+  no thought was given to the possibility that a real implementation would
+  incorporate both VAD versions, to be selected at run time.  However, given our
+  (ThemWi) desire for bit-exact testing against other people's implementations,
+  it made no sense for us to arbitrarily select one VAD version and drop the
+  other - hence we took the unconventional route of incorporating both VAD1 and
+  VAD2 into libtwamr, and designing our encoder API so that library users get
+  to select which VAD they wish to apply.
+
+Like all other Themyscira GSM codec libraries, libtwamr includes the codec
+homing feature in both encoder and decoder directions, as required by 3GPP
+specs.  Furthermore, libtwamr implementation of this codec homing feature
+includes the following simple extensions (simple in terms of low implementation
+cost) to facilitate construction of an AMR-EFR hybrid encoder and decoder:
+
+* In the decoder direction, the main AMR frame decoder function includes a DHF
+  detector as required by 3GPP architecture.  In libtwamr this function can be
+  told to trigger on EFR DHF instead of MR122 version, by way of a flag set in
+  the mode field of the frame structure passed to amr_decode_frame().
+
+* In the encoder direction, the regular call to amr_encode_frame() - standard
+  for AMR - can be followed with a call to amr_dhf_subst_efr() or
+  amr_dhf_subst_efr2() before passing the array of encoded parameters to
+  EFR_params2frame() from libgsmefr.  See AMR-EFR-hybrid-emu article for more
+  information.  The AMR-EFR hybrid test sequences in amr122_efr.zip pass on
+  both amr_dhf_subst_efr() and amr_dhf_subst_efr2() versions, but the latter
+  additionally matches the observable behavior of T-Mobile USA.
+
+The mechanism that allows libtwamr to be used for AMR-EFR hybrid implementation
+(as opposed to the more conventional use case of implementing standard AMR-NB)
+is kept out of the main stateful paths: there are no separate AMR-EFR hybrid
+encoder or decoder sessions that are distinguishable from regular AMR encoding
+and decoding in terms of state.  In the decoder direction, the main AMR frame
+decoder function needs to know which DHF it should check for, but this
+indication is embedded in the mode field in struct amr_param_frame and not in
+the state.  In the encoder direction, the mechanism is a separate function
+(stateless) that needs to be called between amr_encode_frame() and
+EFR_params2frame().  This approach dovetails nicely with the core vs I/O
+separation: the option of AMR-EFR hybrid can be viewed as a different I/O front
+end to the same AMR engine, alongside with 3GPP AMR test sequence and RFC 4867
+I/O options.
+
+Please refer to AMR-library-API article for further details.