diff doc/AMR-library-API @ 480:332397bc80aa

doc/AMR-library-API: document public const data items
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 19 May 2024 23:18:17 +0000
parents 616b7ba1135b
children
line wrap: on
line diff
--- a/doc/AMR-library-API	Sun May 19 22:22:40 2024 +0000
+++ b/doc/AMR-library-API	Sun May 19 23:18:17 2024 +0000
@@ -410,3 +410,44 @@
 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.
+
+Public const data items
+=======================
+
+In addition to all of the functions described above, libtwamr exports some
+public const data items, declared in <tw_amr.h> header file.
+
+AMR storage format file header
+------------------------------
+
+Every .amr file begins with the magic signature "#!AMR\n" (6 bytes); programs
+that read this file format have to check and skip this signature, whereas
+programs that write this file format have to emit it at the beginning.  Libtwamr
+provides both the const datum and its length:
+
+#define	AMR_IETF_HDR_LEN	6	/* .amr file header bytes */
+
+extern const uint8_t amr_file_header_magic[AMR_IETF_HDR_LEN];
+
+DHF bit patterns
+----------------
+
+There are 8 special decoder homing frames (DHFs) defined in 3GPP TS 26.073, one
+for each codec mode; libtwamr implements all 8 AMR DHFs plus the different DHF
+defined for EFR.  The bit patterns of all 9 DHFs implemented in libtwamr are
+exported as public const data items:
+
+extern const int16_t amr_dhf_mr475[AMR_MAX_PRM];
+extern const int16_t amr_dhf_mr515[AMR_MAX_PRM];
+extern const int16_t amr_dhf_mr59[AMR_MAX_PRM];
+extern const int16_t amr_dhf_mr67[AMR_MAX_PRM];
+extern const int16_t amr_dhf_mr74[AMR_MAX_PRM];
+extern const int16_t amr_dhf_mr795[AMR_MAX_PRM];
+extern const int16_t amr_dhf_mr102[AMR_MAX_PRM];
+extern const int16_t amr_dhf_mr122[AMR_MAX_PRM];
+extern const int16_t amr_dhf_gsmefr[AMR_MAX_PRM];
+
+Each DHF bit pattern is implemented and exported in the form of an array of
+broken-down codec parameters for its respective mode.  For extra robustness,
+each of these const int16_t arrays is storage-allocated in the full size of
+AMR_MAX_PRM (57), even for lower codec modes that have fewer parameters.