diff README @ 451:614ae8dc6807

README: update for libgsmfr2+libgsmefr+libtwamr set
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 10 May 2024 02:36:34 +0000
parents 1b8cb3490d48
children
line wrap: on
line diff
--- 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 <gsm.h> 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 <gsm.h> 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.