FreeCalypso > hg > gsm-codec-lib
annotate doc/FR1-library-history @ 581:e2d5cad04cbf
libgsmhr1 RxFE: store CN R0+LPC separately from speech
In the original GSM 06.06 code the ECU for speech mode is entirely
separate from the CN generator, maintaining separate state. (The
main intertie between them is the speech vs CN state variable,
distinguishing between speech and CN BFIs, in addition to the
CN-specific function of distinguishing between initial and update
SIDs.)
In the present RxFE implementation I initially thought that we could
use the same saved_frame buffer for both ECU and CN, overwriting
just the first 4 params (R0 and LPC) when a valid SID comes in.
However, I now realize it was a bad idea: the original code has a
corner case (long sequence of speech-mode BFIs to put the ECU in
state 6, then SID and CN-mode BFIs, then a good speech frame) that
would be broken by that buffer reuse approach. We could eliminate
this corner case by resetting the ECU state when passing through
a CN insertion period, but doing so would needlessly increase
the behavioral diffs between GSM 06.06 and our version.
Solution: use a separate CN-specific buffer for CN R0+LPC parameters,
and match the behavior of GSM 06.06 code in this regard.
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Thu, 13 Feb 2025 10:02:45 +0000 |
parents | 516e84085a15 |
children |
rev | line source |
---|---|
301
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
1 The first Themyscira library for GSM-FR speech codec was libgsmfrp, an add-on |
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
2 to legacy libgsm from TU-Berlin. The current offering is libgsmfr2, which |
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
3 supplants the earlier combination of libgsm+libgsmfrp. This document details |
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
4 the change history in this continuum of GSM-FR codec libraries. |
135
22601ae99434
doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
5 |
534
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
6 libgsmfr2 change history: version 2.0.0 to version 2.1.0 |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
7 ======================================================== |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
8 |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
9 * New functions gsmfr_{preproc,fulldec}_bfi_bits() handle the case of received |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
10 BFI with payload bits included. GSM 06.31 requires that the combination of |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
11 BFI with "accepted SID frame" bit pattern be treated as an invalid SID frame, |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
12 not as an unusable frame; this requirement could not be fulfilled with the |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
13 previous gsmfr_{preproc,fulldec}_bfi() API that only does unusable frame |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
14 handling. |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
15 |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
16 * Several new API functions were added that facilitate the use of our Rx DTX |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
17 preprocessor block as a TFO transform, including the possibility of DTXd. |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
18 |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
19 * Convenience wrapper functions were added for both the full decoder and the |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
20 TFO transform that take RTP input (payload bytes and length), encapsulating |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
21 the logic of TW-TS-001 for both basic and extended RTP formats. |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
22 |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
23 * Sizes of internal state structures are exported as public const "variables" |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
24 (const memory words really), allowing alternative methods of allocating memory |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
25 for these structs besides the standard malloc-calling gsmfr_*_create() |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
26 functions. |
516e84085a15
libgsmfr2 is now at version 2.1.0
Mychaela Falconia <falcon@freecalypso.org>
parents:
301
diff
changeset
|
27 |
301
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
28 Changes from libgsmfrp version 1.0.2 to libgsmfr2 version 2.0.0 |
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
29 =============================================================== |
135
22601ae99434
doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
30 |
301
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
31 * Dependency on <gsm.h> defined types abolished, the entire library uses |
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
32 <stdint.h> types instead. |
135
22601ae99434
doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
33 |
301
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
34 * The Rx DTX handler component of the new library is unchanged from libgsmfrp |
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
35 version 1.0.2, aside from the use of new types: uint8_t instead of gsm_byte, |
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
36 explicit arrays of uint8_t instead of gsm_frame. |
135
22601ae99434
doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
37 |
301
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
38 * In addition to this Rx DTX handler component, the new library includes the |
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
39 GSM 06.10 encoder & decoder component (ported from libgsm pl22), the new |
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
40 full decoder wrapper with decoder homing, an encoder homing function, and |
019eed8b1948
doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
250
diff
changeset
|
41 new stateless frame packing and unpacking functions. |
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
|
42 |
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
|
43 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
|
44 ======================================================== |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
45 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
46 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
|
47 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
|
48 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
49 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
|
50 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
|
51 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
|
52 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
|
53 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
|
54 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
|
55 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
|
56 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
|
57 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
58 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
|
59 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
|
60 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
61 - 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
|
62 - 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
|
63 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
|
64 - 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
|
65 |
731c98b67da1
doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents:
244
diff
changeset
|
66 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
|
67 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
|
68 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
|
69 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
|
70 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
|
71 |
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
|
72 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
|
73 ======================================================== |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
74 |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
75 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
|
76 |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
77 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
|
78 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
|
79 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
|
80 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
|
81 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
|
82 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
|
83 |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
84 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
|
85 (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
|
86 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
|
87 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
|
88 |
fcc0887ff0d0
doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents:
159
diff
changeset
|
89 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
|
90 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
|
91 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
|
92 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
|
93 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
|
94 (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
|
95 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
|
96 are based on the Xmaxc from the last subframe of the most recent SID. |