FreeCalypso > hg > gsm-codec-lib

annotate doc/AMR-library-API @ 476:c84bf526c7eb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
beginning of libtwamr documentation
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 18 May 2024 21:22:07 +0000
parents
children 936a08cc73ce
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
c84bf526c7eb beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
250 Using the AMR decoder
c84bf526c7eb beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
251 =====================
c84bf526c7eb beginning of libtwamr documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
252