# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1716160697 0
# Node ID 332397bc80aa058eab66cc197b0272767619a47a
# Parent  616b7ba1135b55f01a7911d93202309eea6a64ac
doc/AMR-library-API: document public const data items

diff -r 616b7ba1135b -r 332397bc80aa doc/AMR-library-API
--- 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.