FreeCalypso > hg > gsm-codec-lib

annotate doc/FR1-library-history @ 585:3c6bf0d26ee7 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
TW-TS-005 reader: fix maximum line length bug TW-TS-005 section 4.1 states: The maximum allowed length of each line is 80 characters, not including the OS-specific newline encoding. The implementation of this line length limit in the TW-TS-005 hex file reader function in the present suite was wrong, such that lines of the full maximum length could not be read. Fix it. Note that this bug affects comment lines too, not just actual RTP payloads. Neither Annex A nor Annex B features an RTP payload format that goes to the maximum of 40 bytes, but if a comment line goes to the maximum allowed length of 80 characters not including the terminating newline, the bug will be triggered, necessitating the present fix.
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 25 Feb 2025 07:49:28 +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.