FreeCalypso > hg > gsm-codec-lib

annotate doc/FR1-library-API @ 297:6b479cfb06a4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
beginning of libgsmfr2 documentation
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 15 Apr 2024 07:12:31 +0000
parents
children a45f806cada9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Libgsmfr2 general usage
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 =======================
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 The external public interface to Themyscira libgsmfr2 consists of a single
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 header file <tw_gsmfr.h>; it should be installed in some system include
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 directory.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7
6b479cfb06a4 beginning of libgsmfr2 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
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 prototypes), const qualifier is used where appropriate, and the interface is
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 defined in terms of <stdint.h> types; <tw_gsmfr.h> includes <stdint.h>. The
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 use of old libgsm defined types (gsm_byte, gsm_frame and gsm_signal) has been
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 abolished in the migration from libgsm+libgsmfrp to libgsmfr2.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 GSM 06.10 encoder and decoder
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 =============================
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 Both the encoder and the decoder are stateful; each running instance of either
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 element needs its own state structure. However, this GSM 06.10 component of
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 libgsmfr2 shares a peculiar property with old libgsm from which it was derived:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 the same state structure (struct gsmfr_0610_state) is used by both entities.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 Needless to say, each given instance of struct gsmfr_0610_state must be used
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 for only one purpose, either for the encoder or for the decoder; mixing calls
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 to encoder and decoder functions with the same state structure is an invalid
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 operation with undefined results.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 State structures for the basic encoder or decoder are allocated with this
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 function:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 struct gsmfr_0610_state *gsmfr_0610_create(void);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 This function allocates dynamic memory for the state structure with malloc()
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 (the size of the struct is internal to the library and not exposed) and returns
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 a pointer to the allocated and initialized struct if successful, or NULL if
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 malloc() fails. The state structure is malloc'ed as a single chunk, hence when
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 you are done with it, simply free() it.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 The initialization or reset portion of gsmfr_0610_create() operation can always
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 be repeated with this function:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 void gsmfr_0610_reset(struct gsmfr_0610_state *state);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 Immediately after gsmfr_0610_create() or gsmfr_0610_reset(), the "virgin" state
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 structure can be used either for the encoder or for the decoder; however, once
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 that state struct has been passed to functions of either group, it can only be
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 used for that functional group.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 Encoder specifics
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 -----------------
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 The most elementary single-frame processing function of libgsmfr2 GSM 06.10
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 encoder is:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 void gsmfr_0610_encode_params(struct gsmfr_0610_state *st, const int16_t *pcm,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 struct gsmfr_param_frame *param);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 The input is an array of 160 linear PCM samples (left-justified in int16_t),
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 and the output is this structure:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 struct gsmfr_param_frame {
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 int16_t LARc[8];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 int16_t Nc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 int16_t bc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 int16_t Mc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 int16_t xmaxc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 int16_t xMc[4][13];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 };
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 Most of the time the following wrapper function is more useful:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 void gsmfr_0610_encode_frame(struct gsmfr_0610_state *st, const int16_t *pcm,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 uint8_t *frame);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 The output is a 33-byte buffer, filled with the encoded GSM-FR speech frame in
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 the RTP format specified in ETSI TS 101 318 and IETF RFC 3551.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 If the optional encoder homing feature is desired, call this function right
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 after the call to gsmfr_0610_encode_frame() or gsmfr_0610_encode_params():
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 void gsmfr_0610_encoder_homing(struct gsmfr_0610_state *st, const int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 This function checks to see if the PCM frame (160 linear PCM samples) is an EHF;
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 if the input frame is indeed EHF, the function calls gsmfr_0610_reset().
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 Decoder specifics
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 -----------------
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 The internal native form of the 06.10 decoder once again uses
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 struct gsmfr_param_frame:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 void gsmfr_0610_decode_params(struct gsmfr_0610_state *st,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 const struct gsmfr_param_frame *param,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 The more commonly used RTP-format version is:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 void gsmfr_0610_decode_frame(struct gsmfr_0610_state *st, const uint8_t *frame,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 Please note:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 1) The basic GSM 06.10 decoder is just that: there is no SID recognition or DTX
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 handling, every possible input bit pattern will be interpreted and decoded
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 as a GSM 06.10 speech frame.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 2) There is no decoder homing function at this layer, and no check for DHF.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 3) The RTP signature nibble 0xD is ignored (not checked) by
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 gsmfr_0610_decode_frame().
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 Rx DTX preprocessor block
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 =========================
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 The Rx DTX preprocessor is its own stateful element, independent from the 06.10
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 decoder to which it is usually coupled. Libgsmfr2 provides a "fulldec" wrapper
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 that incorporates both elements, but the ability to use the Rx DTX preprocessor
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 by itself still remains, unchanged from our previous libgsmfrp offering. One
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 potential application for this preprocessor by itself, without immediately
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 following it with the GSM 06.10 decode step, is the possibility of implementing
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 the TFO/TrFO transform of 3GPP TS 28.062 section C.3.2.1.1 for GSM-FR: our Rx
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 DTX preprocessor does exactly what that section calls for, specifically in
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 "case 1" where the input UL frame stream may contain SIDs and BFI frame gaps,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122 but the output must be 100% valid frames and SID-free.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124 The state structure for this block is struct gsmfr_preproc_state, and it is
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 allocated with this function:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 struct gsmfr_preproc_state *gsmfr_preproc_create(void);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129 Like other state structures in Themyscira GSM codec libraries, this opaque
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 state is malloc'ed as a single chunk and can be simply freed afterward. A
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131 reset function is also provided:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 void gsmfr_preproc_reset(struct gsmfr_preproc_state *state);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135 Preprocessing good frames
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136 -------------------------
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138 For every good traffic frame (BFI=0) you receive from the radio subsystem, you
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 need to call this preprocessor function:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141 void gsmfr_preproc_good_frame(struct gsmfr_preproc_state *state,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142 uint8_t *frame);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 The second argument is both input and output, i.e., the frame is modified in
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145 place. If the received frame is not SID (specifically, if the SID field
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146 deviates from the SID codeword by 16 or more bits, per GSM 06.31 section 6.1.1),
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147 then the frame (considered a good speech frame) will be left unmodified (i.e.,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 it is to be passed unchanged to the GSM 06.10 decoder), but preprocessor state
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149 will be updated. OTOH, if the received frame is classified as either valid or
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
150 invalid SID per GSM 06.31, then the output frame will contain comfort noise
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151 generated by the preprocessor using a PRNG, or a silence frame in one particular
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
152 corner case.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154 GSM-FR RTP (originally libgsm) 0xD magic: the upper nibble of the first byte
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155 can be anything on input to gsmfr_preproc_good_frame(), but the output frame
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 will always have the correct magic in it.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158 Handling BFI conditions
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159 -----------------------
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 If you received a lost/missing frame indication instead of a good traffic frame,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 call this preprocessor function:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164 void gsmfr_preproc_bfi(struct gsmfr_preproc_state *state, int taf,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
165 uint8_t *frame_out);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
166
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
167 TAF is a flag defined in GSM 06.31 section 6.1.1; if you don't have this flag,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 pass 0 - you will lose the function of comfort noise muting in the event of
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169 prolonged SID loss, but all other Rx DTX functions will still work the same.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171 With this function the 33-byte frame buffer is only an output, i.e., prior
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
172 buffer content is a don't-care and there is no provision for making any use of
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 erroneous frames like in EFR. The frame generated by the preprocessor may be
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174 substitution/muting, comfort noise or silence depending on the state.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
176 GSM-FR full decoder
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177 ===================
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179 The full decoder is a high-level feature of libgsmfr2, incorporating both the
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
180 Rx DTX preprocessor block and the GSM 06.10 decoder block. The state structure
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
181 for the full decoder (struct gsmfr_fulldec_state) internally incorporates both
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
182 struct gsmfr_0610_state and gsmfr_preproc_state, but because it is implemented
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
183 inside libgsmfr2, it is still malloc'ed as a single chunk and can thus be
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 released with a single free() call. The functions for allocating and
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
185 initializing this state follow the established pattern:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
186
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
187 struct gsmfr_fulldec_state *gsmfr_fulldec_create(void);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
188
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
189 void gsmfr_fulldec_reset(struct gsmfr_fulldec_state *state);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
190
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
191 The reset function internally calls gsmfr_0610_reset() and
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
192 gsmfr_preproc_reset(), initializing both processing blocks.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194 Frame processing functions are also straightforward:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
196 void gsmfr_fulldec_good_frame(struct gsmfr_fulldec_state *state,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197 const uint8_t *frame, int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
198
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199 void gsmfr_fulldec_bfi(struct gsmfr_fulldec_state *state, int taf,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
201
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
202 These functions follow the same pattern as gsmfr_preproc_good_frame() and
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
203 gsmfr_preproc_bfi(), but the output is a 160-sample linear PCM buffer. Also
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
204 note that the frame input to gsmfr_fulldec_good_frame() is const, unlike the
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
205 situation with gsmfr_preproc_good_frame() - the copying into a scratchpad
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
206 buffer (on the stack) happens inside this "fulldec" wrapper.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
207
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
208 The "fulldec" layer also adds the decoder homing feature:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
209 gsmfr_fulldec_good_frame() detects decoder homing frames and invokes
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
210 gsmfr_fulldec_reset() when required, and also implements EHF output per the
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
211 spec.