FreeCalypso > hg > gsm-codec-lib

annotate doc/FR1-library-history @ 306:047c198408c8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Utils-overview: update for libgsmfr2
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 15 Apr 2024 23:47:51 +0000
parents 019eed8b1948
children 516e84085a15
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
301
019eed8b1948 doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 250
diff changeset
6 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
7 ===============================================================
135
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
301
019eed8b1948 doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 250
diff changeset
9 * 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
10 <stdint.h> types instead.
135
22601ae99434 doc/FR1-Rx-DTX article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
301
019eed8b1948 doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 250
diff changeset
12 * 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
13 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
14 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
15
301
019eed8b1948 doc/FR1-library-history: new article
Mychaela Falconia <falcon@freecalypso.org>
parents: 250
diff changeset
16 * 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
17 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
18 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
19 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
20
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
21 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
22 ========================================================
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents: 244
diff changeset
23
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents: 244
diff changeset
24 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
25 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
26
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents: 244
diff changeset
27 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
28 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
29 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
30 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
31 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
32 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
33 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
34 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
35
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents: 244
diff changeset
36 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
37 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
38
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2
Mychaela Falconia <falcon@freecalypso.org>
parents: 244
diff changeset
39 - 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
40 - 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
41 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
42 - 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
43
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 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
45 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
46 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
47 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
48 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
49
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
50 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
51 ========================================================
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents: 159
diff changeset
52
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents: 159
diff changeset
53 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
54
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents: 159
diff changeset
55 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
56 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
57 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
58 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
59 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
60 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
61
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents: 159
diff changeset
62 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
63 (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
64 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
65 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
66
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1
Mychaela Falconia <falcon@freecalypso.org>
parents: 159
diff changeset
67 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
68 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
69 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
70 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
71 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
72 (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
73 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
74 are based on the Xmaxc from the last subframe of the most recent SID.