FreeCalypso > hg > gsm-codec-lib
annotate doc/AMR-library-API @ 519:6f8abfe253a4 default tip
gsmhr-dec-craft: works after bugfix
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 01 Sep 2024 20:00:01 +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. |