FreeCalypso > hg > gsm-codec-lib
comparison doc/FR1-library-desc @ 297:6b479cfb06a4
beginning of libgsmfr2 documentation
| author | Mychaela Falconia <falcon@freecalypso.org> |
|---|---|
| date | Mon, 15 Apr 2024 07:12:31 +0000 |
| parents | |
| children |
comparison
equal
deleted
inserted
replaced
| 296:e0d42e87da96 | 297:6b479cfb06a4 |
|---|---|
| 1 Themyscira libgsmfr2 is our new (2024) library offering for GSM FRv1 codec, | |
| 2 replacing the previous combination of libgsm (classic 1990s free sw offering) | |
| 3 and libgsmfrp (our add-on). That combination appeared satisfactory at first | |
| 4 because of how the decoder processing chain is defined for FRv1 (the Rx DTX | |
| 5 handler forms a modular piece, passing a frame of 260 bits to unmodified "pure" | |
| 6 GSM 06.10 decoder), but use of legacy libgsm presents some difficulties: | |
| 7 | |
| 8 * Inconvenience and inconsistency: for all other supported GSM speech codecs, | |
| 9 Themyscira libraries provide the complete solution, not depending on anyone | |
| 10 else's software, but for FRv1 we depended on a library that was created in a | |
| 11 different era for non-GSM applications but just happens, almost by accident, | |
| 12 to be a bit-exact implementation of GSM 06.10 spec. | |
| 13 | |
| 14 * Poor design in frame packing and unpacking functions: the operations of | |
| 15 bit-shuffling a GSM-FR codec frame between the array of parameters form | |
| 16 (76 words) and the packed RTP format used in IP-based GSM RAN (33 bytes) are | |
| 17 stateless pure functions, but their implementations in libgsm (gsm_explode() | |
| 18 and gsm_implode()) require a state structure. (Libgsm supports WAV49 format | |
| 19 in addition to the RTP-adopted one, and WAV49 packing is stateful - but this | |
| 20 WAV49 feature is of no use and no relevance in real GSM applications.) | |
| 21 | |
| 22 * No ability to implement homing: the internal state structure used by libgsm | |
| 23 is set to the home state when it is allocated with gsm_create(), but there is | |
| 24 no reset function, and such function cannot be implemented externally when | |
| 25 the state structure is private to the library and not exposed. Therefore, | |
| 26 the optional codec homing feature defined in later versions of GSM 06.10 spec | |
| 27 cannot be implemented in a wrapper around legacy libgsm, causing the resulting | |
| 28 FOSS implementation to be inferior to existing commercial implementations | |
| 29 (deployed in practice by incumbent nation-scale networks) which do implement | |
| 30 this feature. | |
| 31 | |
| 32 In response to the above issues, we now have a new library named libgsmfr2 that | |
| 33 provides all needed functions for GSM-FR codec "under one roof", harmonized | |
| 34 with our support for other GSM speech codecs. However, the modularity that is | |
| 35 inherent in the way this codec is defined in the specs (contrast with EFR) is | |
| 36 still retained in the design of our library, which exhibits the following 4 | |
| 37 functional divisions: | |
| 38 | |
| 39 1) Libgsmfr2 includes a "pure" GSM 06.10 encoder and decoder, directly | |
| 40 corresponding to old libgsm. This code is in fact lifted from libgsm, | |
| 41 ported into Themyscira gsm-codec-lib style in terms of C dialect, defined | |
| 42 types and naming conventions. The reset function that is missing in libgsm | |
| 43 is now provided, however, fixing that defect. | |
| 44 | |
| 45 2) The Rx DTX handler component is unchanged from our previous libgsmfrp. Per | |
| 46 the relevant specs (GSM 06.11, 06.12 and 06.31) this component is a modular | |
| 47 piece: it emits a standard 260-bit frame of GSM 06.10 parameters that can be | |
| 48 fed to anyone else's implementation of the latter standard. | |
| 49 | |
| 50 3) Full decoder: this component is a wrapper around an 06.10 decoder instance | |
| 51 and an Rx DTX instance, providing functionality equivalent to the standard | |
| 52 decoder function in other GSM speech codecs. | |
| 53 | |
| 54 4) Stateless utility functions for frame format conversions (packing and | |
| 55 unpacking) and for incoming SID classification. An application can freely | |
| 56 use just these functions, without pulling in any encoder or decoder or | |
| 57 stateful preprocessor functionality, making the present library very | |
| 58 convenient for debug utilities. | |
| 59 | |
| 60 The homing feature is available in both encoder and decoder directions, but it | |
| 61 is implemented differently between the two: | |
| 62 | |
| 63 * In the encoder direction, if the application wishes to enable the possibility | |
| 64 of in-band homing, it needs to call gsmfr_0610_encoder_homing() after the | |
| 65 regular call to gsmfr_0610_encode_frame() or gsmfr_0610_encode_params(). | |
| 66 | |
| 67 * In the decoder direction, the homing feature is always included if one uses | |
| 68 the "fulldec" (full decoder) wrapper (it is implemented in that layer), and | |
| 69 never included if one uses the "basic" GSM 06.10 decoder by itself, or the | |
| 70 Rx DTX handler block by itself. | |
| 71 | |
| 72 The only major feature of GSM-FR codec that is currently absent in libgsmfr2 is | |
| 73 application of DTX in the encoder direction: GSM 06.32 VAD followed by DTX | |
| 74 hangover logic and SID output. This omission is currently acceptable for | |
| 75 Themyscira Wireless: DTXd (DTX in the radio downlink direction) is not allowed | |
| 76 when each BTS operates at only one carrier frequency, which makes it pointless | |
| 77 to enable DTX for speech encoding at the network edge transcoder, and we are not | |
| 78 trying to replace TI Calypso DSP on the MS side of GSM. However, if this | |
| 79 situation changes and some need arises for a FOSS implementation of DTX-enabled | |
| 80 GSM-FR encoder, the architecture of Themyscira libgsmfr2 should make it possible | |
| 81 to integrate such addition. |