FreeCalypso > hg > gsm-codec-lib

annotate doc/FR1-library-history @ 536:a3300483ae74

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 21 Sep 2024 20:48:58 +0000
parents 516e84085a15
children
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
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.