# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1716157360 0
# Node ID 616b7ba1135b55f01a7911d93202309eea6a64ac
# Parent  936a08cc73cea1effd905a991e0f66bb0373537b
doc/AMR-library-API: document AMR-EFR hybrid decoder

diff -r 936a08cc73ce -r 616b7ba1135b doc/AMR-library-API
--- a/doc/AMR-library-API	Sun May 19 21:32:31 2024 +0000
+++ b/doc/AMR-library-API	Sun May 19 22:22:40 2024 +0000
@@ -386,3 +386,27 @@
 
 The return value is 0 if tx_type is valid and *rx_type has been filled
 accordingly, or -1 if tx_type is invalid.
+
+AMR-EFR hybrid decoder
+======================
+
+To use libtwamr as an AMR-EFR hybrid decoder, follow these steps:
+
+* Turn the input frame from EFR RTP format into array-of-parameters form with
+  libgsmefr function EFR_frame2params(), writing the output into the param[]
+  array in struct amr_param_frame.
+
+* Set 'type' in the struct to RX_SPEECH_GOOD for good frames, RX_SPEECH_BAD for
+  BFI with payload bits present, or RX_NO_DATA for BFI without payload.
+
+* Set 'mode' to 0x87 always, indicating a variation of MR122 with EFR DHF
+  instead of the different native MR122 DHF.
+
+* Call amr_decode_frame() with this input.
+
+Fundamental limitation: the AMR decoder in libtwamr, derived from 3GPP AMR
+reference source and only minimally extended to support EFR DHF, does not
+support EFR SID frames.  Therefore, the option of AMR-EFR hybrid emulation via
+libtwamr is limited to lab experiments where the input to the decoder can be
+ensured to be SID-free, and is not suitable for production use.  See
+AMR-EFR-philosophy article for more information.