diff doc/AMR-library-API @ 479:616b7ba1135b

doc/AMR-library-API: document AMR-EFR hybrid decoder
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 19 May 2024 22:22:40 +0000
parents 936a08cc73ce
children 332397bc80aa
line wrap: on
line diff
--- 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.