FreeCalypso > hg > gsm-codec-lib

annotate doc/FR1-Rx-DTX @ 268:0cfb7c95cce2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
libgsmfr2: integrate lpc.c from libgsm
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 14 Apr 2024 01:50:48 +0000
parents 731c98b67da1
children 4034c2b06ec8
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.
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.