FreeCalypso > hg > gsm-codec-lib

annotate doc/FR1-library-API @ 536:a3300483ae74

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 21 Sep 2024 20:48:58 +0000
parents bf7bbc7d494f
children
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()
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
32 and returns a pointer to the allocated and initialized struct if successful, or
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
33 NULL if malloc() fails. The state structure is malloc'ed as a single chunk,
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
34 hence when you are done with it, simply free() it.
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 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
37 be repeated with this function:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 void gsmfr_0610_reset(struct gsmfr_0610_state *state);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
41 To support applications that need (or prefer) to use some different method of
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
42 managing their memory allocations, the library also exports this const datum:
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
43
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
44 extern const unsigned gsmfr_0610_state_size;
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
45
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
46 Using this feature, one can replace gsmfr_0610_create() with something like the
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
47 following (example for applications based on Osmocom libraries):
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
48
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
49 struct gsmfr_0610_state *st;
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
50 st = talloc_size(ctx, gsmfr_0610_state_size);
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
51 if (st)
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
52 gsmfr_0610_reset(st);
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
53
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 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
55 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
56 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
57 used for that functional group.
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 Encoder specifics
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 -----------------
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 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
63 encoder is:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 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
66 struct gsmfr_param_frame *param);
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 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
69 and the output is this structure:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 struct gsmfr_param_frame {
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 int16_t LARc[8];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 int16_t Nc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 int16_t bc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 int16_t Mc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 int16_t xmaxc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 int16_t xMc[4][13];
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
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 Most of the time the following wrapper function is more useful:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 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
83 uint8_t *frame);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 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
86 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
87
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 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
89 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
90
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 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
92
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 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
94 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
95
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 Decoder specifics
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 -----------------
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 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
100 struct gsmfr_param_frame:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 void gsmfr_0610_decode_params(struct gsmfr_0610_state *st,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 const struct gsmfr_param_frame *param,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 The more commonly used RTP-format version is:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 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
109 int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 Please note:
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 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
114 handling, every possible input bit pattern will be interpreted and decoded
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 as a GSM 06.10 speech frame.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 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
118
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 3) The RTP signature nibble 0xD is ignored (not checked) by
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 gsmfr_0610_decode_frame().
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122 Rx DTX preprocessor block
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
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 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
126 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
127 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
128 by itself still remains, unchanged from our previous libgsmfrp offering. One
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
129 significant application for this preprocessor by itself, without immediately
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
130 following it with the GSM 06.10 decode step, is the TFO/TrFO transform of 3GPP
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
131 TS 28.062 section C.3.2.1.1 for GSM-FR: our Rx DTX preprocessor does exactly
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
132 what that section calls for, specifically in "case 1" where the input UL frame
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
133 stream may contain SIDs and BFI frame gaps, but the output must be 100% valid
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
134 frames and SID-free. The current version of libgsmfr2 includes some additional
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
135 provisions for using our preprocessor block as a TFO transform in both non-DTXd
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
136 and DTXd-enabled configurations, as detailed in a later section of this
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
137 document.
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 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
140 allocated with this function:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142 struct gsmfr_preproc_state *gsmfr_preproc_create(void);
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 Like other state structures in Themyscira GSM codec libraries, this opaque
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145 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
146 reset function is also provided:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 void gsmfr_preproc_reset(struct gsmfr_preproc_state *state);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
150 There is also a public const datum with the size of this structure, allowing
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
151 use of talloc and other alternative schemes:
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
152
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
153 extern const unsigned gsmfr_preproc_state_size;
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
154
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155 Preprocessing good frames
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 -------------------------
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 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
159 need to call this preprocessor function:
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 void gsmfr_preproc_good_frame(struct gsmfr_preproc_state *state,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 uint8_t *frame);
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 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
165 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
166 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
167 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
168 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
169 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
170 invalid SID per GSM 06.31, then the output frame will contain comfort noise
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
171 generated by the preprocessor using a PRNG, or a speech muting or silence frame
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
172 in some corner cases involving invalid SID.
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174 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
175 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
176 will always have the correct magic in it.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
178 There is also a variant of this function (implemented as a wrapper) that applies
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
179 homing logic:
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
180
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
181 void gsmfr_preproc_good_frame_hm(struct gsmfr_preproc_state *state,
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
182 uint8_t *frame);
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
183
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
184 This function operates just like plain gsmfr_preproc_good_frame() except for
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
185 one difference: if the input matches the decoder homing frame (DHF), the state
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
186 is reset with an internal call to gsmfr_preproc_reset(). (Because the DHF is
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
187 still a good speech frame, it is always passed through to the output unchanged
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
188 by both functions - the only difference is the effect on subsequent state.)
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
189 The homing version of good frame preproc is intended for TFO applications, and
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
190 is invoked internally by gsmfr_tfo_xfrm_main() function described in a later
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
191 section of this document.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
192
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193 Handling BFI conditions
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194 -----------------------
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 If you received a lost/missing frame indication instead of a good traffic frame,
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
197 call one of these preprocessor functions:
297
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_preproc_bfi(struct gsmfr_preproc_state *state, int taf,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 uint8_t *frame_out);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
201
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
202 or
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
203
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
204 void gsmfr_preproc_bfi_bits(struct gsmfr_preproc_state *state,
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
205 const uint8_t *bad_frame, int taf,
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
206 uint8_t *frame_out);
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
207
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
208 gsmfr_preproc_bfi_bits() should be called if you received payload bits along
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
209 with the BFI flag; plain gsmfr_preproc_bfi() should be called if you received
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
210 BFI with no data. The bad frame passed to gsmfr_preproc_bfi_bits() is used
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
211 only to check if the BFI should be handled as an invalid SID rather than the
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
212 more common case of an unusable frame - see GSM 06.31 for definitions of these
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
213 terms. Past the SID check, the bad frame content is a don't-care, and there is
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
214 no provision for making any use of erroneous frames like in EFR.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
215
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
216 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
217 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
218 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
219
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
220 With both functions the 33-byte buffer pointed to by frame_out is only an
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
221 output, i.e., prior buffer content is a don't-care. The frame generated by the
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
222 preprocessor may be substitution/muting, comfort noise or silence depending on
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
223 the state.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
224
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
225 gsmfr_preproc_bfi_bits() arguments bad_frame and frame_out can point to the
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
226 same memory: the function finishes analyzing bad_frame input before it starts
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
227 writing to frame_out.
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
228
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
229 GSM-FR full decoder
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
230 ===================
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
231
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
232 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
233 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
234 for the full decoder (struct gsmfr_fulldec_state) internally incorporates both
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
235 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
236 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
237 released with a single free() call. The functions for allocating and
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
238 initializing this state follow the established pattern:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
239
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
240 struct gsmfr_fulldec_state *gsmfr_fulldec_create(void);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
241
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
242 void gsmfr_fulldec_reset(struct gsmfr_fulldec_state *state);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
243
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
244 extern const unsigned gsmfr_fulldec_state_size;
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
245
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
246 The reset function internally calls gsmfr_0610_reset() and
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
247 gsmfr_preproc_reset(), initializing both processing blocks.
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
248
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
249 Frame processing functions are also straightforward:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
250
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
251 void gsmfr_fulldec_good_frame(struct gsmfr_fulldec_state *state,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
252 const uint8_t *frame, int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
253
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
254 void gsmfr_fulldec_bfi(struct gsmfr_fulldec_state *state, int taf,
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
255 int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
256
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
257 void gsmfr_fulldec_bfi_bits(struct gsmfr_fulldec_state *state,
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
258 const uint8_t *bad_frame, int taf, int16_t *pcm);
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
259
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
260 These functions follow the same pattern as gsmfr_preproc_good_frame(),
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
261 gsmfr_preproc_bfi() and gsmfr_preproc_bfi_bits(), but the output is a 160-sample
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
262 linear PCM buffer. Also note that the frame input to gsmfr_fulldec_good_frame()
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
263 is const, unlike the situation with gsmfr_preproc_good_frame() - the copying
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
264 into a scratchpad buffer (on the stack) happens inside this "fulldec" wrapper.
297
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
265
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
266 The "fulldec" layer also adds the decoder homing feature:
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
267 gsmfr_fulldec_good_frame() detects decoder homing frames and invokes
6b479cfb06a4 beginning of libgsmfr2 documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
268 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
269 spec.
298
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
270
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
271 Full decoder RTP input
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
272 ----------------------
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
273
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
274 If a network element is receiving GSM-FR input via RTP and needs to feed this
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
275 input to the decoder, the RTP payload handler needs to support both the basic
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
276 RTP format of ETSI TS 101 318 (also RFC 3551) and the extended RTP format of
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
277 TW-TS-001. Depending on the format received, and depending on bit flags in the
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
278 TEH octet in the case of TW-TS-001, one of the 3 main processing functions
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
279 listed above will need to be called. Seeing that this complex logic should be
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
280 abstracted away from applications into the library, we've added the following
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
281 wrapper function:
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
282
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
283 int gsmfr_fulldec_rtp_in(struct gsmfr_fulldec_state *state,
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
284 const uint8_t *rtp_pl, unsigned rtp_pl_len,
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
285 int16_t *pcm);
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
286
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
287 The input is the received RTP payload: array of bytes and length. It is
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
288 acceptable to pass 0 as rtp_pl_len, in which case rtp_pl pointer can be NULL.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
289 The function proceeds as follows:
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
290
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
291 * If the input is valid RTP format for GSM-FR (either basic or extended), it is
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
292 passed to the appropriate main processing function. Unlike the permissive
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
293 stance taken in lower-level functions, RTP input validation includes a check
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
294 of 0xD signature of GSM-FR, as well as validation of TEH octet signature and
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
295 consistency in the case of TW-TS-001. The return value is 0, indicating that
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
296 good input was received.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
297
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
298 * If the input is a zero-length payload (rtp_pl_len is 0, rtp_pl may be NULL),
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
299 it is treated like BFI-no-data with TAF=0. The return value is 0, meaning
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
300 that this input is still considered valid.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
301
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
302 * All other inputs are considered invalid. Linear PCM output is still generated
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
303 by calling gsmfr_fulldec_bfi(), but the return value is -1, signaling invalid
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
304 RTP input.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
305
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
306 TFO transform
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
307 =============
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
308
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
309 "TFO transform" is the term adopted by Themyscira Wireless for the non-trivial
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
310 transform on GSM codec frames called for by the TFO spec, 3GPP TS 28.062
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
311 section C.3.2.1.1. For each of the 3 classic GSM codecs, this transform can
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
312 operate in two modes:
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
313
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
314 DTXd=0: the input UL frame stream from call leg A may contain SIDs and BFI
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
315 frame gaps, but the output to call leg B DL must be 100% valid frames and
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
316 SID-free.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
317
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
318 DTXd=1: the output to call leg B DL is allowed to contain both good speech and
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
319 valid SID frames, just like the output of a DTX-enabled speech encoder.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
320 Furthermore, it can be presumed that network operators who enable DTXd seek to
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
321 reap its benefits in terms of radio interference reduction, hence the
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
322 DTXd-enabled TFO transform should actually make use of DTXd capability.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
323
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
324 In the case of GSM-FR codec, the TFO transform with DTXd=0 is identical to the
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
325 Rx DTX preprocessor part of the standard endpoint decoder, hence our "preproc"
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
326 block is directly suited to serve as such. OTOH, the case of DTXd=1 is
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
327 different: heeding the implied need to actually make use of DTXd when possible
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
328 requires implementing a transform that is not the same as the preprocessor to
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
329 be applied just prior to local GSM 06.10 decoding, hence the DTXd-enabled TFO
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
330 transform is a different entity.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
331
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
332 The approach implemented in Themyscira libgsmfr2 is a hybrid:
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
333
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
334 * The preprocessor block described earlier in this document functions both as
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
335 the necessary component of the full endpoint decoder and as the TFO transform
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
336 for DTXd=0.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
337
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
338 * TFO transform for DTXd=1 is implemented as a two-step process:
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
339
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
340 1) Regular main processing functions of the preproc block produce output that
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
341 is SID-free, containing synthetic "speech" frames in the case of comfort
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
342 noise or silence.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
343
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
344 2) A special post-processor function needs to be called immediately afterward.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
345 This function selectively transforms some output frames into SIDs based on
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
346 a flag set in the state structure.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
347
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
348 In order to make this approach possible, all main processing functions of the
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
349 preproc block do a little bit of extra housekeeping to keep track of whether or
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
350 not their output can be replaced with SID, logic that is unnecessary when this
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
351 block functions as part of the full endpoint decoder or as non-DTXd TFO
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
352 transform. However, this logic is very simple and the overhead is very light.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
353
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
354 TFO transform API
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
355 -----------------
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
356
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
357 The state structure was already described earlier: it is
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
358 struct gsmfr_preproc_state, created either with gsmfr_preproc_create() or by
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
359 externally allocating the needed memory based on gsmfr_preproc_state_size and
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
360 then initializing it with gsmfr_preproc_reset(). The following API functions
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
361 are then available:
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
362
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
363 int gsmfr_tfo_xfrm_main(struct gsmfr_preproc_state *state,
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
364 const uint8_t *rtp_in, unsigned rtp_in_len,
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
365 uint8_t *frame_out);
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
366
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
367 int gsmfr_tfo_xfrm_dtxd(struct gsmfr_preproc_state *state, uint8_t *frame_out);
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
368
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
369 gsmfr_tfo_xfrm_main() is the TFO transform counterpart to
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
370 gsmfr_fulldec_rtp_in(), described in detail earlier. It is also possible (and
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
371 allowed) to call gsmfr_preproc_* main processing functions directly, but the
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
372 RTP wrapper is convenient for the same reasons as in the case of the full
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
373 decoder. In this mode of usage, the only difference between the full decoder
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
374 and the TFO transform is that the former emits linear PCM output, whereas the
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
375 latter emits 33-byte GSM-FR codec frames to be sent to call leg B downlink.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
376
536
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
Mychaela Falconia <falcon@freecalypso.org>
parents: 535
diff changeset
377 The return value from gsmfr_tfo_xfrm_main() is the same as that of
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
Mychaela Falconia <falcon@freecalypso.org>
parents: 535
diff changeset
378 gsmfr_fulldec_rtp_in(): 0 if the the RTP input was considered good or -1 if it
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
Mychaela Falconia <falcon@freecalypso.org>
parents: 535
diff changeset
379 is invalid. In the case of invalid RTP input that produces -1 return value,
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
Mychaela Falconia <falcon@freecalypso.org>
parents: 535
diff changeset
380 gsmfr_tfo_xfrm_main() calls gsmfr_preproc_bfi(), just like how
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
Mychaela Falconia <falcon@freecalypso.org>
parents: 535
diff changeset
381 gsmfr_fulldec_rtp_in() calls gsmfr_fulldec_bfi() under the same conditions.
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
Mychaela Falconia <falcon@freecalypso.org>
parents: 535
diff changeset
382
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
383 If DTXd is in use, then the call to gsmfr_tfo_xfrm_main() needs to be directly
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
384 followed by a call to gsmfr_tfo_xfrm_dtxd(), operating on the same output buffer
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
385 with the same state structure. The output will then be changed to SID when
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
386 appropriate for the current state.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
387
536
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
Mychaela Falconia <falcon@freecalypso.org>
parents: 535
diff changeset
388 The return value from gsmfr_tfo_xfrm_dtxd() is the SP flag of GSM 06.31: 1 if
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
Mychaela Falconia <falcon@freecalypso.org>
parents: 535
diff changeset
389 the output frame is speech or 0 if it is SID.
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
Mychaela Falconia <falcon@freecalypso.org>
parents: 535
diff changeset
390
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
391 TFO transform homing
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
392 --------------------
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
393
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
394 3GPP specs are silent on whether or not TFO transforms should implement homing,
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
395 i.e., whether or not they should reset to home state when a decoder homing frame
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
396 passes through. However, at Themyscira Wireless we believe in building
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
397 deterministic systems whose bit-exact behavior can be modeled and relied upon;
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
398 for this reason, our implementation of TFO transform does include in-band
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
399 homing. In accord with this design decision, gsmfr_tfo_xfrm_main() internally
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
400 calls gsmfr_preproc_good_frame_hm() described earlier instead of plain
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
401 gsmfr_preproc_good_frame().
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
402
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
403 With DTXd=1, if a stream of DHFs is input to the TFO transform, the same stream
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
404 of DHFs will appear on the output, i.e., DTXd won't kick in. (The same behavior
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
405 occurs in a standard 3GPP-compliant speech encoder whose input is a stream of
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
406 0xD5 octets in PCMA or 0xFE in PCMU.) However, any BFIs following this DHF
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
407 will be immediately converted to SID, under the same conditions when our TFO
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
408 transform with DTXd=0 emits silence frames of GSM 06.11.
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
409
298
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
410 Stateless utility functions
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
411 ===========================
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
412
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
413 Conversions between RTP packed format and broken-down codec parameters are
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
414 stateless and implemented with highly efficient code. There are two versions;
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
415 this version converts between packed frames and struct gsmfr_param_frame used
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
416 by 06.10 encoder and decoder functions:
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
417
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
418 void gsmfr_pack_frame(const struct gsmfr_param_frame *param, uint8_t *frame);
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
419 void gsmfr_unpack_frame(const uint8_t *frame, struct gsmfr_param_frame *param);
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
420
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
421 and this version converts between packed frames and a straight linear array of
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
422 76 parameters:
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
423
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
424 void gsmfr_pack_from_array(const int16_t *params, uint8_t *frame);
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
425 void gsmfr_unpack_to_array(const uint8_t *frame, int16_t *params);
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
426
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
427 The latter functions gsmfr_pack_from_array() and gsmfr_unpack_to_array() are
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
428 drop-in replacements for gsm_implode() and gsm_explode() from old libgsm. The
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
429 order of parameters in this array is the canonical one: first all LARc, then
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
430 all params for the first subframe, then the second subframe, then the third and
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
431 the fourth. OTOH, struct gsmfr_param_frame uses functional grouping, chosen
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
432 for ease of porting of original libgsm code.
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
433
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
434 Both unpacking functions (gsmfr_unpack_frame() and gsmfr_unpack_to_array())
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
435 ignore the upper nibble of the first byte, i.e., the 0xD signature is not
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
436 enforced. However, this signature is always set correctly by gsmfr_pack_frame()
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
437 and gsmfr_pack_from_array(), and also by gsmfr_0610_encode_frame() function
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
438 which calls gsmfr_pack_frame() as its finishing step.
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
439
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
440 The last remaining stateless utility function performs SID classification of
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
441 received GSM-FR frames:
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
442
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
443 int gsmfr_preproc_sid_classify(const uint8_t *frame);
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
444
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
445 This function analyzes an RTP-encoded FR frame (the upper nibble of the first
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
446 byte is NOT checked for 0xD signature) for the SID codeword of GSM 06.12 and
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
447 classifies the frame as SID=0, SID=1 or SID=2 per the rules of GSM 06.31
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
448 section 6.1.1. This classification is the first processing step performed by
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
449 gsmfr_preproc_good_frame().
299
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
450
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
451 Public constant definitions
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
452 ===========================
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
453
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
454 Our public header file <tw_gsmfr.h> provides these constant definitions, which
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
455 should be self-explanatory:
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
456
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
457 #define GSMFR_RTP_FRAME_LEN 33
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
458 #define GSMFR_NUM_PARAMS 76
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
459
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
460 Public const data items
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
461 =======================
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
462
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
463 There are two special GSM-FR frame bit patterns defined in the specs: there is
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
464 the silence frame of GSM 06.11, and there is the decoder homing frame specified
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
465 in later versions of GSM 06.10. RTP-packed representations of both frames are
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
466 included in libgsmfr2, and are made public:
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
467
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
468 extern const uint8_t gsmfr_preproc_silence_frame[GSMFR_RTP_FRAME_LEN];
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
469 extern const uint8_t gsmfr_decoder_homing_frame[GSMFR_RTP_FRAME_LEN];