annotate README @ 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 614ae8dc6807
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1 Themyscira Wireless GSM codec libraries & utilities package
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
2 ===========================================================
0
b45bb0f9bdfc README: indicate purpose and scope of this repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
4 Themyscira Wireless, a technical initiative of the Women's Republic of
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
5 Themyscira, is proud to present this package of GSM codec libraries and
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
6 associated command line test and development utilities. The present package
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
7 provides the following linkable C libraries, intended to be usable by any
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
8 application that needs GSM codec functionality:
0
b45bb0f9bdfc README: indicate purpose and scope of this repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
10 libgsmfr2 This library implements the original GSM-FR codec, consisting
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
11 of not only the basic transcoding functions of GSM 06.10, but
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
12 also all Rx DTX handler functions that are required for a speech
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
13 decoder receiving a stream of frames from a radio interface,
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
14 either MS or network side. This library is a replacement for
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
15 classic libgsm, providing proper reset logic, homing functions
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
16 and the Rx DTX handler block.
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
17
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
18 libgsmefr This library implements GSM-EFR codec, based on the reference
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
19 code from ETSI (GSM 06.53). The bit-exact version of GSM-EFR
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
20 implemented here is the original one, not the AMR-EFR hybrid
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
21 that was made into a permissible implementation option after
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
22 the development of AMR.
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
23
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
24 libtwamr This library implements 3GPP AMR-NB codec, based on the official
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
25 reference code (TS 26.073). Both VAD versions are included,
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
26 selected by the user application at run time, and I/O functions
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
27 are provided for both 3GPP test sequence format and the more
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
28 practical format of IETF RFC 4867. This library can also be
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
29 used to implement AMR-EFR hybrid operation if no DTX is needed
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
30 in the encoder and if the input to the decoder contains no SID
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
31 frames.
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
32
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
33 The only GSM codec for which no implementation library is currently provided is
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
34 GSM-HR, also known as HRv1. Librification of HRv1 reference code from ETSI is
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
35 a planned work item for future development.
0
b45bb0f9bdfc README: indicate purpose and scope of this repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
37 The libraries provided here are intended for two primary purposes:
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
38
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
39 1) They are used as part of Themyscira Wireless MGW (media gateway)
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
40 implementation, providing the necessary speech transcoder between a GSM
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
41 network and G.711-based PSTN.
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
42
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
43 2) They are useful in many varied study and exploration workings, as part of
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
44 experiments where it becomes necessary to model, simulate or replicate
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
45 bit-exact operation of someone else's network element.
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
46
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
47 Each of our Themyscira core libraries is free-standing and independent of the
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
48 others. The dependency on classic libgsm (by way of <gsm.h> header file) that
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
49 existed in previous versions of Themyscira gsm-codec-lib suite has been
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
50 eliminated; the present version has zero dependencies.
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
51
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
52 Included command line utilities
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
53 ===============================
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
54
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
55 In addition to the set of core libraries, the present package includes a number
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
56 of command line utilities, falling into the following groups:
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
57
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
58 * Some utilities specifically exercise and test our core libraries;
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
59
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
60 * Some utilities are not specifically for library testing but make use of
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
61 these libraries;
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
62
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
63 * Some utilities are included because they implement some closely related and
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
64 relevant debug and development functionality, even though they don't link
451
614ae8dc6807 README: update for libgsmfr2+libgsmefr+libtwamr set
Mychaela Falconia <falcon@freecalypso.org>
parents: 206
diff changeset
65 with any of the included core libraries.
206
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
66
1b8cb3490d48 README: update for work approaching release
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
67 Please see the included documentation in the doc subdirectory.