# HG changeset patch # User Mychaela Falconia # Date 1715308594 0 # Node ID 614ae8dc68070b34d976ee05565e0403a13a431b # Parent 16bc3036cc849c6bb2055395e26142bbd6ccb314 README: update for libgsmfr2+libgsmefr+libtwamr set diff -r 16bc3036cc84 -r 614ae8dc6807 README --- a/README Fri May 10 01:48:20 2024 +0000 +++ b/README Fri May 10 02:36:34 2024 +0000 @@ -4,44 +4,64 @@ Themyscira Wireless, a technical initiative of the Women's Republic of Themyscira, is proud to present this package of GSM codec libraries and associated command line test and development utilities. The present package -provides two linkable C libraries, intended to be usable by any application -that needs GSM codec functionality: +provides the following linkable C libraries, intended to be usable by any +application that needs GSM codec functionality: -libgsmefr An implementation of EFR codec in the same spirit as classic - libgsm, i.e., like libgsm, but for EFR instead of 06.10. It is - based on the reference code from ETSI. +libgsmfr2 This library implements the original GSM-FR codec, consisting + of not only the basic transcoding functions of GSM 06.10, but + also all Rx DTX handler functions that are required for a speech + decoder receiving a stream of frames from a radio interface, + either MS or network side. This library is a replacement for + classic libgsm, providing proper reset logic, homing functions + and the Rx DTX handler block. -libgsmfrp An Rx DTX handler preprocessor to be invoked prior to - gsm_decode() from classic libgsm, implementing GSM 06.11, 06.12 - and 06.31 functionality in the Rx direction. +libgsmefr This library implements GSM-EFR codec, based on the reference + code from ETSI (GSM 06.53). The bit-exact version of GSM-EFR + implemented here is the original one, not the AMR-EFR hybrid + that was made into a permissible implementation option after + the development of AMR. -These two libraries are intended primarily for use as part of GSM network -deployment, i.e., as part of the necessary speech transcoder implementation in -whichever network-side server process acts as the voice gateway to PSTN or -other networks. However, they can also be used as part of development and -testing on the mobile side of GSM: for example, to decode TCH downlink bits and -voice memo recordings read out of FreeCalypso GSM MS devices, or to implement -your own lab-oriented GSM MS on top of some other PHY. +libtwamr This library implements 3GPP AMR-NB codec, based on the official + reference code (TS 26.073). Both VAD versions are included, + selected by the user application at run time, and I/O functions + are provided for both 3GPP test sequence format and the more + practical format of IETF RFC 4867. This library can also be + used to implement AMR-EFR hybrid operation if no DTX is needed + in the encoder and if the input to the decoder contains no SID + frames. + +The only GSM codec for which no implementation library is currently provided is +GSM-HR, also known as HRv1. Librification of HRv1 reference code from ETSI is +a planned work item for future development. -Each of these two Themyscira libraries (libgsmefr and libgsmfrp) is free- -standing and independent of the other. libgsmfrp makes use of header -file from libgsm (for gsm_byte and gsm_frame defined types) and requires this -header file in order to compile; libgsmefr has zero dependencies nominally but -will often be used together with libgsm and libgsmfrp. +The libraries provided here are intended for two primary purposes: + +1) They are used as part of Themyscira Wireless MGW (media gateway) + implementation, providing the necessary speech transcoder between a GSM + network and G.711-based PSTN. + +2) They are useful in many varied study and exploration workings, as part of + experiments where it becomes necessary to model, simulate or replicate + bit-exact operation of someone else's network element. + +Each of our Themyscira core libraries is free-standing and independent of the +others. The dependency on classic libgsm (by way of header file) that +existed in previous versions of Themyscira gsm-codec-lib suite has been +eliminated; the present version has zero dependencies. Included command line utilities =============================== -In addition to the two main libraries, the present package includes a number of -command line utilities, falling into the following groups: +In addition to the set of core libraries, the present package includes a number +of command line utilities, falling into the following groups: -* Some utilities specifically exercise and test the two core libraries; +* Some utilities specifically exercise and test our core libraries; * Some utilities are not specifically for library testing but make use of - our libraries; + these libraries; * Some utilities are included because they implement some closely related and relevant debug and development functionality, even though they don't link - with either libgsmefr or libgsmfrp. + with any of the included core libraries. Please see the included documentation in the doc subdirectory.