FreeCalypso > hg > gsm-codec-lib
annotate doc/FR1-Rx-DTX @ 263:ffdcdb27d673
libgsmfr2: integrate e/d state from TU-Berlin code
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sat, 13 Apr 2024 01:10:37 +0000 |
parents | 731c98b67da1 |
children | 4034c2b06ec8 |
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. |
244
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
161 |
250
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
162 libgsmfrp change history: version 1.0.1 to version 1.0.2 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
163 ======================================================== |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
164 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
165 There are only two changes, both involving corner cases with invalid SID frames |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
166 being received: |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
167 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
168 1) An invalid SID frame was received immediately following a good speech frame. |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
169 In this case we start CN generation, but we take the needed LARc and Xmaxc |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
170 parameters from the last speech frame, instead of the usual procedure of |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
171 extracting them from a valid SID frame. The change from 1.0.1 to 1.0.2 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
172 concerns the Xmaxc parameter in this corner case: in 1.0.1 we took Xmaxc |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
173 from the last subframe and used it for ensuing CN generation, but in 1.0.2 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
174 we compute a more proper mean Xmaxc from all 4 subframes, by dequantizing, |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
175 summing and requantizing. |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
176 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
177 2) An invalid SID frame was received in the speech muting state. The sequence |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
178 of inputs would have to be: |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
179 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
180 - a good speech frame; |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
181 - one or more BFIs, but not too many, so that the cached speech frame |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
182 does not decay fully by Xmaxc reduction; |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
183 - an invalid SID frame. |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
184 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
185 In version 1.0.1 we handled this even more obscure corner case by entering |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
186 the CN muting state, i.e., the state that is normally entered upon the |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
187 second lost SID. In version 1.0.2 we ignore invalid SID in the speech |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
188 muting state and act as if we got BFI, i.e., continue speech muting rather |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
189 than switch to CN muting. |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
190 |
244
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
191 libgsmfrp change history: version 1.0.0 to version 1.0.1 |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
192 ======================================================== |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
193 |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
194 Version 1.0.0 exhibited the following defects, which are fixed in 1.0.1: |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
195 |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
196 1) The last received valid SID was cached forever for the purpose of |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
197 handling future invalid SIDs - we could have received some valid |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
198 SID ages ago, then lots of speech or NO_DATA, and if we then get |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
199 an invalid SID, we would resurrect the last valid SID from ancient |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
200 history - a bad design. In our new design, we handle invalid SID |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
201 based on the current state, much like BFI. |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
202 |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
203 2) GSM 06.11 spec says clearly that after the second lost SID |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
204 (received BFI=1 && TAF=1 in CN state) we need to gradually decrease |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
205 the output level, rather than jump directly to emitting silence |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
206 frames - we previously failed to implement such logic. |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
207 |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
208 3) Per GSM 06.12 section 5.2, Xmaxc should be the same in all 4 subframes |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
209 in a SID frame. What should we do if we receive an otherwise valid |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
210 SID frame with different Xmaxc? Our previous approach would |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
211 replicate this Xmaxc oddity in every subsequent generated CN frame, |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
212 which is rather bad. In our new design, the very first CN frame |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
213 (which can be seen as a transformation of the SID frame itself) |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
214 retains the original 4 distinct Xmaxc, but all subsequent CN frames |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
215 are based on the Xmaxc from the last subframe of the most recent SID. |