gsm-codec-lib: doc/AMR-library-API annotate

annotate doc/AMR-library-API @ 581:e2d5cad04cbf

libgsmhr1 RxFE: store CN R0+LPC separately from speech In the original GSM 06.06 code the ECU for speech mode is entirely separate from the CN generator, maintaining separate state. (The main intertie between them is the speech vs CN state variable, distinguishing between speech and CN BFIs, in addition to the CN-specific function of distinguishing between initial and update SIDs.) In the present RxFE implementation I initially thought that we could use the same saved_frame buffer for both ECU and CN, overwriting just the first 4 params (R0 and LPC) when a valid SID comes in. However, I now realize it was a bad idea: the original code has a corner case (long sequence of speech-mode BFIs to put the ECU in state 6, then SID and CN-mode BFIs, then a good speech frame) that would be broken by that buffer reuse approach. We could eliminate this corner case by resetting the ECU state when passing through a CN insertion period, but doing so would needlessly increase the behavioral diffs between GSM 06.06 and our version. Solution: use a separate CN-specific buffer for CN R0+LPC parameters, and match the behavior of GSM 06.06 code in this regard.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Thu, 13 Feb 2025 10:02:45 +0000
parents	332397bc80aa
children

rev	line source
476 c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 Libtwamr general usage
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 ======================
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	3
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	4 The external public interface to Themyscira libtwamr consists of a single
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	5 header file <tw_amr.h>; it should be installed in some system include
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	6 directory.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	7
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	8 The dialect of C used by all Themyscira GSM codec libraries is ANSI C (function
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	9 prototypes), const qualifier is used where appropriate, and the interface is
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	10 defined in terms of <stdint.h> types; <tw_amr.h> includes <stdint.h>.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	11
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	12 Public #define constant definitions
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	13 ===================================
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	14
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	15 Libtwamr public API header file <tw_amr.h> defines these constants:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	16
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	17 #define AMR_MAX_PRM 57 /* max. num. of params */
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	18 #define AMR_IETF_MAX_PL 32 /* max bytes in RFC 4867 frame */
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	19 #define AMR_IETF_HDR_LEN 6 /* .amr file header bytes */
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	20 #define AMR_COD_WORDS 250 /* # of words in 3GPP test seq format */
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	21
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	22 Explanation:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	23
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	24 * AMR_MAX_PRM is the maximum number of broken-down speech parameters in the
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	25 highest 12k2 mode of AMR; this definition is needed for struct amr_param_frame
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	26 covered later in this document.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	27
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28 * AMR_IETF_MAX_PL is the size of the output buffer that must be provided for
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	29 amr_frame_to_ietf(), and also most commonly the size of the staging buffer
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	30 which most applications will likely use for gathering the input to
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31 amr_frame_from_ietf().
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	32
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	33 * AMR_IETF_HDR_LEN is the size of amr_file_header_magic[] public const datum
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	34 covered later in this document, and this constant will also be needed by any
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	35 application that needs to read or write the fixed header at the beginning of
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	36 .amr files.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	37
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	38 * AMR_COD_WORDS is the number of 16-bit words in one encoded frame in 3GPP test
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	39 sequence format (.cod); the public definition is needed for sizing the arrays
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	40 used with amr_frame_to_tseq() and amr_frame_from_tseq() API functions.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	41
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	42 Libtwamr enumerated types
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	43 =========================
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	44
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	45 Libtwamr public API header file <tw_amr.h> defines these 3 enums:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	46
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	47 enum RXFrameType {
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	48 RX_SPEECH_GOOD = 0,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	49 RX_SPEECH_DEGRADED,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	50 RX_ONSET,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	51 RX_SPEECH_BAD,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	52 RX_SID_FIRST,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	53 RX_SID_UPDATE,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	54 RX_SID_BAD,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	55 RX_NO_DATA,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	56 RX_N_FRAMETYPES /* number of frame types */
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	57 };
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	58
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	59 enum TXFrameType {
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	60 TX_SPEECH_GOOD = 0,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	61 TX_SID_FIRST,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	62 TX_SID_UPDATE,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	63 TX_NO_DATA,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	64 TX_SPEECH_DEGRADED,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	65 TX_SPEECH_BAD,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	66 TX_SID_BAD,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	67 TX_ONSET,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	68 TX_N_FRAMETYPES /* number of frame types */
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	69 };
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	70
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	71 enum Mode {
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	72 MR475 = 0,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	73 MR515,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	74 MR59,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	75 MR67,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	76 MR74,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	77 MR795,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	78 MR102,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	79 MR122,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	80 MRDTX
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	81 };
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	82
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	83 Rx and Tx frame types are as defined by 3GPP, and the numeric values assigned
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	84 to each type are the same as those used by the official TS 26.073 encoder and
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	85 decoder programs. Note that Rx and Tx frame types are NOT equal!
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	86
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	87 enum Mode should be self-explanatory: it covers the 8 possible codec modes of
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	88 AMR, plus the pseudo-mode of MRDTX used for packing and format manipulation of
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	89 SID frames.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	90
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	91 State allocation and freeing
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	92 ============================
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	93
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	94 In order to use the AMR encoder, you will need to allocate an encoder state
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	95 structure, and to use the AMR decoder, you will need to allocate a decoder state
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	96 structure. The necessary state allocation functions are:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	97
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	98 struct amr_encoder_state *amr_encoder_create(int dtx, int use_vad2);
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	99 struct amr_decoder_state *amr_decoder_create(void);
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	100
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	101 struct amr_encoder_state and struct amr_decoder_state are opaque structures to
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	102 library users: you only get pointers which you remember and pass around, but
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	103 <tw_amr.h> does not give you full definitions of these structs. As a library
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	104 user, you don't even get to know the size of these structs, hence the necessary
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	105 malloc() operation happens inside amr_encoder_create() and amr_decoder_create().
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	106 However, each structure is malloc'ed as a single chunk, hence when you are done
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	107 with it, simply call free() to relinquish each encoder or decoder state
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	108 instance.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	109
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	110 amr_encoder_create() and amr_decoder_create() functions can fail if the malloc()
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	111 call inside fails, in which case the two libtwamr functions in question return
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	112 NULL.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	113
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	114 The dtx argument to amr_encoder_create() is a Boolean flag represented as an
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	115 int; it tells the AMR encoder whether it should operate with DTX enabled or
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	116 disabled. (Note that DTX is also called SCR for Source-Controlled Rate in some
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	117 AMR specs.) The use_vad2 argument is another Boolean flag, also represented as
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	118 an int; it tells the AMR encoder to use VAD2 algorithm instead of VAD1. It is
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	119 a novel feature of libtwamr in that both VAD versions are included and
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	120 selectable at run time; see AMR-library-desc article for the details.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	121
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	122 State reset functions
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	123 ---------------------
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	124
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	125 The state of an already-allocated AMR encoder or AMR decoder can be reset at
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	126 any time with these functions:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	127
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	128 void amr_encoder_reset(struct amr_encoder_state *st, int dtx, int use_vad2);
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	129 void amr_decoder_reset(struct amr_decoder_state *st);
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	130
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	131 Note that the two extra arguments to amr_encoder_reset() are the same as the
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	132 arguments to amr_encoder_create() - the reset operation is complete.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	133 amr_encoder_create() is a wrapper around malloc() followed by
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	134 amr_encoder_reset(), and amr_decoder_create() is a wrapper around malloc()
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	135 followed by amr_decoder_reset().
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	136
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	137 Using the AMR encoder
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	138 =====================
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	139
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	140 To encode one 20 ms audio frame per AMR, call amr_encode_frame():
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	141
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	142 void amr_encode_frame(struct amr_encoder_state *st, enum Mode mode,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	143 const int16_t pcm, struct amr_param_frame frame);
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	144
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	145 You need to provide an encoder state structure allocated earlier with
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	146 amr_encoder_create(), the selection of which codec mode to use, and a block of
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	147 160 linear PCM samples. Only modes MR475 through MR122 are valid for 'mode'
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	148 argument to amr_encode_frame(); MRDTX is not allowed in this context.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	149
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	150 The output from amr_encode_frame() is written into this structure:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	151
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	152 struct amr_param_frame {
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	153 uint8_t type;
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	154 uint8_t mode;
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	155 int16_t param[AMR_MAX_PRM];
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	156 };
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	157
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	158 This structure is public, but it is defined by libtwamr (not by any external
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	159 standard), and it is generally intended to be an intermediate stage before
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	160 output encoding. Library functions exist for generating 3 output formats: 3GPP
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	161 AMR test sequence format, IETF RFC 4867 format, and AMR-EFR hybrid.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	162
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	163 Native encoder output
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	164 ---------------------
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	165
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	166 The output structure is filled as follows:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	167
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	168 type: Set to one of TX_SPEECH_GOOD, TX_SID_FIRST, TX_SID_UPDATE or TX_NO_DATA,
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	169 as defined by 3GPP. The last 3 are possible only when the encoder
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	170 operates with DTX enabled.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	171
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	172 mode: One of MR475 through MR122, same as the 'mode' argument to
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	173 amr_encode_frame().
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	174
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	175 param: Array of codec parameters, from 17 to 57 of them for modes MR475 through
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	176 MR122 in the case of TX_SPEECH_GOOD output, or 5 parameters for MRDTX
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	177 in the case of TX_SID_FIRST, TX_SID_UPDATE or TX_NO_DATA DTX output.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	178
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	179 3GPP AMR test sequence output
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	180 -----------------------------
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	181
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	182 The following function exists to convert the above encoder output into the test
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	183 sequence format which 3GPP defined for AMR, the insanely inefficient one with
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	184 250 (AMR_COD_WORDS) 16-bit words per frame:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	185
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	186 void amr_frame_to_tseq(const struct amr_param_frame frame, uint16_t cod);
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	187
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	188 This function allows libtwamr encoder to be tested for correctness against the
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	189 set of test sequences in 3GPP TS 26.074. The output is in the local machine's
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	190 native byte order.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	191
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	192 RFC 4867 output
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	193 ---------------
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	194
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	195 To turn libtwamr encoder output into an octet-aligned RFC 4867 single-frame
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	196 payload or storage-format frame (ToC octet followed by speech or SID data, but
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	197 no CMR payload header), call this function:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	198
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	199 unsigned amr_frame_to_ietf(const struct amr_param_frame frame, uint8_t bytes);
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	200
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	201 The output buffer must have room for up to 32 bytes (AMR_IETF_MAX_PL); the
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	202 return value is the actual number of bytes used. The shortest possible output
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	203 is 1 byte in the case of TX_NO_DATA; the longest possible output is 32 bytes in
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	204 the case of TX_SPEECH_GOOD, mode MR122.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	205
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	206 Additional notes regarding output conversion functions
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	207 ------------------------------------------------------
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	208
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	209 The struct amr_param_frame that is input to amr_frame_to_ietf() or
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	210 amr_frame_to_tseq() is expected to be a valid output from amr_encode_frame().
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	211 These output conversion functions contain no guards against invalid input
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	212 (anything that cannot occur in the output from amr_encode_frame()), and are
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	213 thus allowed to segfault or corrupt memory etc if fed such invalid input.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	214
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	215 This lack of guard is justified in the present instance because struct
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	216 amr_param_frame is not intended to ever function as an external interface to
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	217 untrusted entities, instead this struct is intended to be only an intermediate
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	218 staging buffer between the call to amr_encode_frame() and an immediately
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	219 following call to one of the provided output conversion functions.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	220
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	221 AMR-EFR hybrid encoder
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	222 ======================
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	223
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	224 To use libtwamr as an AMR-EFR hybrid encoder, follow these constraints:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	225
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	226 * 'dtx' argument must be 0 (no DTX) on the call to amr_encoder_create() or
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	227 amr_encoder_reset() that establishes the state for the encoder session.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	228
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	229 * 'mode' argument to amr_encode_frame() must be MR122 on every frame.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	230
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	231 After getting struct amr_param_frame out of amr_encode_frame(), call one of
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	232 these functions to generate the correct EFR DHF under the right conditions:
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	233
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	234 void amr_dhf_subst_efr(struct amr_param_frame *frame);
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	235 void amr_dhf_subst_efr2(struct amr_param_frame frame, const int16_t pcm);
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	236
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	237 Both functions check if the encoded frame is MR122 DHF (type equals
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	238 TX_SPEECH_GOOD, mode equals MR122, param array equals the fixed bit pattern of
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	239 MR122 DHF), and if so, overwrite param[] array in the structure with the
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	240 different bit pattern of EFR DHF. The difference between the two functions is
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	241 that amr_dhf_subst_efr() performs the just-described substitution
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	242 unconditionally, whereas amr_dhf_subst_efr2() applies this substitution only if
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	243 the PCM input is EHF. The latter function matches the observed behavior of
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	244 T-Mobile USA, but perhaps some others implemented the simpler logic equivalent
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	245 to our first function.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	246
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	247 After this transformation, call EFR_params2frame() from libgsmefr (see
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	248 EFR-library-API) with param[] array in struct amr_param_frame as input.
c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	249
478 936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	250 Using the AMR decoder: native interface
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	251 =======================================
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	252
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	253 The internal native form of the stateful AMR decoder engine is:
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	254
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	255 void amr_decode_frame(struct amr_decoder_state *st,
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	256 const struct amr_param_frame frame, int16_t pcm);
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	257
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	258 The input frame is given as struct amr_param_frame, same structure as is used
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	259 for the output of the encoder. However, the required input to
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	260 amr_decode_frame() is different from amr_encode_frame() output:
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	261
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	262 * The 'type' member of the struct must be a code from enum RXFrameType, not
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	263 enum TXFrameType!
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	264
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	265 * All 3GPP-defined Rx frame types are allowed.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	266
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	267 * The 'mode' member of the input struct is ignored if the Rx frame type is
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	268 RX_NO_DATA, but must be valid for every other frame type.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	269
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	270 If frame->type is not RX_NO_DATA, frame->mode is interpreted as follows:
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	271
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	272 * The 3 least significant bits (mask 0x07) are taken to indicate the codec mode
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	273 used for this frame;
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	274
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	275 * The most significant bit (mask 0x80) has meaning only if the mode is MR122
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	276 and frame->type is RX_SPEECH_GOOD. Under these conditions, if this bit is
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	277 set, the DHF check is modified to match against the bit pattern of EFR DHF
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	278 instead of regular MR122 DHF.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	279
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	280 amr_decode_frame() contains no guards against invalid (undefined) frame types
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	281 in frame->type, or against any of the codec parameters being out of range.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	282 struct amr_param_frame coming into this function must come only from trusted
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	283 sources inside the application program, usually from one of the provided input
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	284 format conversion functions.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	285
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	286 Decoder homing frame check
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	287 --------------------------
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	288
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	289 The definition of AMR decoder per 3GPP includes two mandatory checks for the
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	290 possibility of the input frame being one of the defined per-mode decoder homing
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	291 frames (DHFs): one check at the beginning of the decoder, checking only up to
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	292 the first subframe and acting only when the current state is homed, and the
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	293 second check at the end of the decoder, checking all parameters (the full frame)
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	294 and resetting the decoder on match.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	295
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	296 This DHF check operation, called from those two places in the stateful decoder
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	297 as just described, is factored out into its own function that is exported as
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	298 part of the public API:
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	299
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	300 int amr_check_dhf(const struct amr_param_frame *frame, int first_sub_only);
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	301
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	302 struct amr_param_frame needs to be passed to amr_check_dhf() as if it was
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	303 amr_decode_frame(); the latter function in fact calls amr_check_dhf() on its
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	304 input. The Boolean flag argument (first_sub_only) tells the function to check
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	305 only to the end of the first subframe if nonzero, or check the entire frame if
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	306 zero. The return value is 1 if the input matches DHF, 0 otherwise.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	307
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	308 frame->type must be RX_SPEECH_GOOD for the frame to be a DHF candidate, and the
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	309 interpretation of frame->mode, including the special mode of matching against
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	310 EFR DHF, is implemented in this function.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	311
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	312 Using the AMR decoder: input preparation
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	313 ========================================
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	314
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	315 Stateless utility functions are provided for preparing decoder inputs,
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	316 converting from RFC 4867 or 3GPP test sequence format into the internal form
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	317 described above.
476 c84bf526c7eb beginning of libtwamr documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	318
478 936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	319 Decoding RFC 4867 input
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	320 -----------------------
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	321
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	322 If the entire RFC 4867 frame (read from .amr storage format or received in RTP
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	323 as an octet-aligned payload) is already in memory, decode it with this function:
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	324
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	325 int amr_frame_from_ietf(const uint8_t bytes, struct amr_param_frame frame);
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	326
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	327 The string of bytes input to this function must begin with the ToC octet. Out
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	328 of this ToC octet, only bits falling under the mask 0x7C (FT and Q bit fields)
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	329 are checked. The remaining 3 bits are not checked: in the case of .amr storage
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	330 format, RFC 4867 describes these bits as "padding" (P bits) and stipulates that
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	331 they MUST be ignored by readers. However, in the case of RTP payloads received
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	332 in a live session, the uppermost bit of the ToC octet becomes F rather than P,
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	333 and it is the responsibility of the application to ensure that F=0: multiframe
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	334 payloads are NOT supported.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	335
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	336 FT in the input frame may be [0,7] (MR475 through MR122), 8 (MRDTX) or 15
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	337 (AMR_FT_NODATA). In all of these cases amr_frame_from_ietf() succeeds and
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	338 returns 0 to indicate so; the resulting struct amr_param_frame is then good to
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	339 be passed to amr_decode_frame(). OTOH, if FT falls into the invalid range of
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	340 [9,14], amr_frame_from_ietf() returns -1 to indicate invalid input.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	341
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	342 Applications that read from a .amr file will need to read just the ToC (aka
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	343 frame header) octet and decode it to determine how many additional octets need
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	344 to be read to absorb one frame. Similarly, RTP applications may need to
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	345 validate incoming payloada by cross-checking between the FT indicated in the
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	346 ToC octet and the received payload length. Both applications can use this
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	347 function:
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	348
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	349 int amr_ietf_grok_first_octet(uint8_t fo);
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	350
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	351 The argument is the first octet, and the function only considers the FT field
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	352 thereof. The return value is:
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	353
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	354 -1 for invalid FT [9,14]
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	355 0 for FT=15 (the ToC octet is the entirety of the payload)
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	356 >0 for valid FT [0,8], indicating the number of additional bytes to be read
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	357
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	358 Decoding 3GPP test sequence input
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	359 ---------------------------------
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	360
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	361 To decode a frame from 3GPP .cod file format, call this function:
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	362
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	363 int amr_frame_from_tseq(const uint16_t *cod, int use_rxtype,
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	364 struct amr_param_frame *frame);
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	365
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	366 The argument 'use_rxtype' should be 1 if the input uses Rx frame types (enum
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	367 RXFrameType) or 0 if it uses Tx frame types (enum TXFrameType); this argument
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	368 directly corresponds to -rxframetype command line option in the reference
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	369 decoder program from 3GPP.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	370
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	371 Unlike raw amr_decode_frame(), amr_frame_from_tseq() does guard against invalid
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	372 input. The return value from this function is:
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	373
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	374 0 means the input was good and the output is good to pass to amr_decode_frame();
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	375 -1 means the frame type field in the input is invalid;
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	376 -2 means the mode field in the input is invalid.
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	377
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	378 Frame type conversion
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	379 ---------------------
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	380
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	381 The operation of mapping from enum TXFrameType to enum RXFrameType, optionally
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	382 but very commonly invoked from amr_frame_from_tseq(), is factored out into its
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	383 own function, exported as part of the public API:
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	384
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	385 int amr_txtype_to_rxtype(enum TXFrameType tx_type, enum RXFrameType *rx_type);
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	386
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	387 The return value is 0 if tx_type is valid and *rx_type has been filled
936a08cc73ce doc/AMR-library-API: describe the decoder Mychaela Falconia <falcon@freecalypso.org> parents: 476 diff changeset	388 accordingly, or -1 if tx_type is invalid.
479 616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	389
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	390 AMR-EFR hybrid decoder
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	391 ======================
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	392
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	393 To use libtwamr as an AMR-EFR hybrid decoder, follow these steps:
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	394
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	395 * Turn the input frame from EFR RTP format into array-of-parameters form with
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	396 libgsmefr function EFR_frame2params(), writing the output into the param[]
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	397 array in struct amr_param_frame.
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	398
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	399 * Set 'type' in the struct to RX_SPEECH_GOOD for good frames, RX_SPEECH_BAD for
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	400 BFI with payload bits present, or RX_NO_DATA for BFI without payload.
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	401
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	402 * Set 'mode' to 0x87 always, indicating a variation of MR122 with EFR DHF
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	403 instead of the different native MR122 DHF.
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	404
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	405 * Call amr_decode_frame() with this input.
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	406
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	407 Fundamental limitation: the AMR decoder in libtwamr, derived from 3GPP AMR
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	408 reference source and only minimally extended to support EFR DHF, does not
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	409 support EFR SID frames. Therefore, the option of AMR-EFR hybrid emulation via
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	410 libtwamr is limited to lab experiments where the input to the decoder can be
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	411 ensured to be SID-free, and is not suitable for production use. See
616b7ba1135b doc/AMR-library-API: document AMR-EFR hybrid decoder Mychaela Falconia <falcon@freecalypso.org> parents: 478 diff changeset	412 AMR-EFR-philosophy article for more information.
480 332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	413
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	414 Public const data items
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	415 =======================
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	416
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	417 In addition to all of the functions described above, libtwamr exports some
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	418 public const data items, declared in <tw_amr.h> header file.
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	419
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	420 AMR storage format file header
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	421 ------------------------------
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	422
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	423 Every .amr file begins with the magic signature "#!AMR\n" (6 bytes); programs
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	424 that read this file format have to check and skip this signature, whereas
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	425 programs that write this file format have to emit it at the beginning. Libtwamr
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	426 provides both the const datum and its length:
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	427
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	428 #define AMR_IETF_HDR_LEN 6 /* .amr file header bytes */
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	429
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	430 extern const uint8_t amr_file_header_magic[AMR_IETF_HDR_LEN];
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	431
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	432 DHF bit patterns
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	433 ----------------
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	434
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	435 There are 8 special decoder homing frames (DHFs) defined in 3GPP TS 26.073, one
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	436 for each codec mode; libtwamr implements all 8 AMR DHFs plus the different DHF
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	437 defined for EFR. The bit patterns of all 9 DHFs implemented in libtwamr are
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	438 exported as public const data items:
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	439
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	440 extern const int16_t amr_dhf_mr475[AMR_MAX_PRM];
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	441 extern const int16_t amr_dhf_mr515[AMR_MAX_PRM];
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	442 extern const int16_t amr_dhf_mr59[AMR_MAX_PRM];
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	443 extern const int16_t amr_dhf_mr67[AMR_MAX_PRM];
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	444 extern const int16_t amr_dhf_mr74[AMR_MAX_PRM];
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	445 extern const int16_t amr_dhf_mr795[AMR_MAX_PRM];
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	446 extern const int16_t amr_dhf_mr102[AMR_MAX_PRM];
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	447 extern const int16_t amr_dhf_mr122[AMR_MAX_PRM];
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	448 extern const int16_t amr_dhf_gsmefr[AMR_MAX_PRM];
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	449
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	450 Each DHF bit pattern is implemented and exported in the form of an array of
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	451 broken-down codec parameters for its respective mode. For extra robustness,
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	452 each of these const int16_t arrays is storage-allocated in the full size of
332397bc80aa doc/AMR-library-API: document public const data items Mychaela Falconia <falcon@freecalypso.org> parents: 479 diff changeset	453 AMR_MAX_PRM (57), even for lower codec modes that have fewer parameters.

FreeCalypso > hg > gsm-codec-lib

annotate doc/AMR-library-API @ 581:e2d5cad04cbf