FreeCalypso > hg > gsm-codec-lib

annotate doc/AMR-library-API @ 555:62943a1ad64e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FR1-Rx-DTX-detail: grammar fix
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 11 Oct 2024 00:22:47 +0000
parents 332397bc80aa
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.