Themyscira Wireless GSM codec libraries & utilities package
===========================================================

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 the following linkable C libraries, intended to be usable by any
application that needs GSM codec functionality:

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.

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.

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.

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 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 our core libraries;

* Some utilities are not specifically for library testing but make use of
  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 any of the included core libraries.

Please see the included documentation in the doc subdirectory.