annotate doc/FR1-Rx-DTX @ 242:f081a6850fb5

libgsmfrp: new refined implementation The previous implementation exhibited the following defects, which are now fixed: 1) The last received valid SID was cached forever for the purpose of handling future invalid SIDs - we could have received some valid SID ages ago, then lots of speech or NO_DATA, and if we then get an invalid SID, we would resurrect the last valid SID from ancient history - a bad design. In our new design, we handle invalid SID based on the current state, much like BFI. 2) GSM 06.11 spec says clearly that after the second lost SID (received BFI=1 && TAF=1 in CN state) we need to gradually decrease the output level, rather than jump directly to emitting silence frames - we previously failed to implement such logic. 3) Per GSM 06.12 section 5.2, Xmaxc should be the same in all 4 subframes in a SID frame. What should we do if we receive an otherwise valid SID frame with different Xmaxc? Our previous approach would replicate this Xmaxc oddity in every subsequent generated CN frame, which is rather bad. In our new design, the very first CN frame (which can be seen as a transformation of the SID frame itself) retains the original 4 distinct Xmaxc, but all subsequent CN frames are based on the Xmaxc from the last subframe of the most recent SID.
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 09 May 2023 05:16:31 +0000
parents aa4cdab30dc8
children fcc0887ff0d0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
135
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 At the level of provided functionality and architectural structure, ETSI GSM
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 specifications for DTX (discontinuous transmission) are very symmetric between
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 FR and EFR: the same DTX functionality is specified for both codecs, with the
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 same overall architecture. However, there is one important difference: in the
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 case of EFR the complete implementation of all DTX functions (for both Tx and
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 Rx) forms an integral and inseparable part of the reference codec (implemented
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 in C) from the beginning, whereas in the case of FR1 the addition of DTX is
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 somewhat of an afterthought. GSM 06.10 defines a "pure" FR codec without any
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 DTX functions, and this most basic spec can be and has been implemented in this
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 "pure" form - classic Unix libgsm from 1990s is a proper, fully compliant
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 implementation of GSM 06.10, but only this spec, without any DTX. In contrast,
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 there has never existed a "pure" implementation of GSM 06.60 EFR codec without
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 associated Tx and Rx DTX functions. Furthermore, there is an important
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 distinction between Tx and Rx DTX handlers for FR1:
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 * Anyone who seeks to implement Tx DTX for FR1 would have to dig into the guts
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 of GSM 06.10 encoder and augment it with VAD and SID encoding functions per
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 GSM 06.32 and 06.12 specs.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 * In contrast, the Rx DTX handler for FR1 is modular: the way it is specified
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 in GSM 06.11, 06.12 and 06.31 is a front-end to unmodified GSM 06.10 decoder.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 On the Rx side, the interface from the radio subsystem to the Rx DTX handler
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 consists of 260 bits of frame plus BFI and TAF flags (the spec also defines a
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 SID flag, but it is determined from frame payload bits), and then the
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 interface from the Rx DTX handler to the GSM 06.10 decoder is another FR frame
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 of 260 bits.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 What are the implications of this situation for the GSM published-source
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 software community? Prior to the present libgsmfrp offering, there has always
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 been libgsm, but no Rx DTX handler. If you are working with a GSM uplink RTP
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 stream from a BTS or a GSM downlink frame stream read out of TI Calypso DSP or
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 some other GSM MS PHY, feeding that stream directly to libgsm (without passing
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 through an Rx DTX handler) is NOT acceptable: a "bare" GSM 06.10 decoder won't
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 recognize SID frames and won't produce the expected comfort noise output, and
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 what are you going to do in those 20 ms windows in which no good traffic frame
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 was received? The situation becomes especially bad (unkind on ears) if you are
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 reading received downlink frames out of TI Calypso DSP: the DSP's buffer will
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 have *some* bit content in every 20 ms window, but naturally this bit content
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 will be garbage during those frame windows when no good frame was received;
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 feeding that garbage to libgsm produces noises that are very unkind on ears.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 The correct solution is to implement an Rx DTX handler, pass the stream of
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 frames and flags from the BTS or the MS PHY to this handler first, and then pass
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 the output of this handler to libgsm 06.10 decoder. Themyscira libgsmfrp is a
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 Free Software implementation of Rx DTX handler for GSM FR, implementing SID
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 classification, comfort noise generation and error concealment.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 Effect of extra preprocessing
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 =============================
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 One key detail deserves extra emphasis before going into library API details:
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 if the input to libgsmfrp consists entirely of good speech frames (no SID frames
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 and no BFIs), then the preprocessor becomes an identity transform. Therefore,
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 if the output of our libgsmfrp preprocessor were to be fed to an additional
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 instance of the same further down the processing chain, no extra transformation
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 of any kind will happen.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 Using libgsmfrp
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 ===============
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 The external public interface to Themyscira libgsmfrp consists of a single
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 header file <gsm_fr_preproc.h>; it should be installed in the same system
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 include directory as <gsm.h> from libgsm. Please note that <gsm_fr_preproc.h>
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 includes <gsm.h>, as needed for gsm_byte and gsm_frame defined types.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 The dialect of C we chose for libgsmfrp is ANSI C (function prototypes), const
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 qualifier is used where appropriate; however, unlike libgsmefr, the interface
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 to libgsmfrp is defined in terms of gsm_byte type defined in <gsm.h>, included
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 from <gsm_fr_preproc.h>.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 State allocation and freeing
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 ============================
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 The Rx DTX handler is stateful, hence you will need to allocate a preprocessor
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 state structure in addition to the usual libgsm state structure for your GSM FR
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 Rx session. The necessary function is:
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 extern struct gsmfr_preproc_state *gsmfr_preproc_create(void);
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 struct gsmfr_preproc_state is an opaque structure to library users: you only get
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 a pointer which you remember and pass around, but <gsm_fr_preproc.h> does not
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 give you a full definition of this struct. As a library user, you don't even
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 get to know the size of this struct, hence the necessary malloc() operation
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 happens inside gsmfr_preproc_create(). However, the structure is malloc'ed as
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 a single chunk, hence when you are done with it, simply call free() on the
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 pointer you got from gsmfr_preproc_create().
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 gsmfr_preproc_create() can fail if the malloc() call inside fails, in which case
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 it returns NULL.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 Preprocessing good frames
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 =========================
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 For every good traffic frame (BFI=0) you receive from the radio subsystem, you
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 need to call this preprocessor function:
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 extern void gsmfr_preproc_good_frame(struct gsmfr_preproc_state *state,
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 gsm_byte *frame);
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 The second argument is both input and output, i.e., the frame is modified in
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 place. If the received frame is not SID (specifically, if the SID field
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 deviates from the SID codeword by 16 or more bits, per GSM 06.31 section 6.1.1),
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 then the frame (considered a good speech frame) will be left unmodified (i.e.,
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 it is to be passed unchanged to the GSM 06.10 decoder), but preprocessor state
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 will be updated. OTOH, if the received frame is classified as either valid or
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 invalid SID per GSM 06.31, then the output frame will contain comfort noise
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 generated by the preprocessor using a PRNG, or a silence frame in one particular
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 corner case.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 GSM-FR RTP (or libgsm) 0xD magic: the upper nibble of the first byte can be
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 anything on input to gsmfr_preproc_good_frame(), but the output frame will
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 always have the correct magic in it.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 Handling BFI conditions
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 =======================
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 If you received a lost/missing frame indication instead of a good traffic frame,
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 call this preprocessor function:
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 extern void gsmfr_preproc_bfi(struct gsmfr_preproc_state *state, int taf,
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 gsm_byte *frame_out);
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 TAF is a flag defined in GSM 06.31 section 6.1.1; if you don't have this flag,
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124 pass 0 - you will lose the function of comfort noise muting in the event of
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 prolonged SID loss, but all other Rx DTX functions will still work the same.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 With this function the 33-byte frame buffer is only an output, i.e., prior
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 buffer content is a don't-care and there is no provision for making any use of
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129 erroneous frames like in EFR. The frame generated by the preprocessor may be
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 substitution/muting, comfort noise or silence depending on the state.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132 Other miscellaneous functions
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 =============================
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135 extern void gsmfr_preproc_reset(struct gsmfr_preproc_state *state);
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137 This function resets the preprocessor state to what it is right out of
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138 gsmfr_preproc_create(), which is naturally just a combination of malloc() and
159
aa4cdab30dc8 doc/FR1-Rx-DTX: typo fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 135
diff changeset
139 gsmfr_preproc_reset(). Given that our Rx DTX handler state is much simpler
135
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140 than, for example, EFR codec state, there does not seem to be any need for
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141 explicit resets, but the reset function is made public for the sake of
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142 completeness.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 extern int gsmfr_preproc_sid_classify(const gsm_byte *frame);
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146 This function analyzes an RTP-encoded FR frame (the upper nibble of the first
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147 byte is NOT checked for 0xD signature) for the SID codeword of GSM 06.12 and
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 classifies the frame as SID=0, SID=1 or SID=2 per the rules of GSM 06.31
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149 section 6.1.1.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
150
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151 Silence frame datum
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
152 ===================
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154 extern const gsm_frame gsmfr_preproc_silence_frame;
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 Many implementors make the mistake of thinking that a GSM FR silence frame is a
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157 frame of 260 zero bits, but the official specs disagree: the silence frame given
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158 in GSM 06.11 (3GPP TS 46.011, at the very end of the spec) is quite different.
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159 Themyscira libgsmfrp implements the correct silence frame per the spec, and that
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160 datum is also made public.