view doc/FR1-library-history @ 534:516e84085a15

libgsmfr2 is now at version 2.1.0
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 20 Sep 2024 00:17:35 +0000
parents 019eed8b1948
children
line wrap: on
line source

The first Themyscira library for GSM-FR speech codec was libgsmfrp, an add-on
to legacy libgsm from TU-Berlin.  The current offering is libgsmfr2, which
supplants the earlier combination of libgsm+libgsmfrp.  This document details
the change history in this continuum of GSM-FR codec libraries.

libgsmfr2 change history: version 2.0.0 to version 2.1.0
========================================================

* New functions gsmfr_{preproc,fulldec}_bfi_bits() handle the case of received
  BFI with payload bits included.  GSM 06.31 requires that the combination of
  BFI with "accepted SID frame" bit pattern be treated as an invalid SID frame,
  not as an unusable frame; this requirement could not be fulfilled with the
  previous gsmfr_{preproc,fulldec}_bfi() API that only does unusable frame
  handling.

* Several new API functions were added that facilitate the use of our Rx DTX
  preprocessor block as a TFO transform, including the possibility of DTXd.

* Convenience wrapper functions were added for both the full decoder and the
  TFO transform that take RTP input (payload bytes and length), encapsulating
  the logic of TW-TS-001 for both basic and extended RTP formats.

* Sizes of internal state structures are exported as public const "variables"
  (const memory words really), allowing alternative methods of allocating memory
  for these structs besides the standard malloc-calling gsmfr_*_create()
  functions.

Changes from libgsmfrp version 1.0.2 to libgsmfr2 version 2.0.0
===============================================================

* Dependency on <gsm.h> defined types abolished, the entire library uses
  <stdint.h> types instead.

* The Rx DTX handler component of the new library is unchanged from libgsmfrp
  version 1.0.2, aside from the use of new types: uint8_t instead of gsm_byte,
  explicit arrays of uint8_t instead of gsm_frame.

* In addition to this Rx DTX handler component, the new library includes the
  GSM 06.10 encoder & decoder component (ported from libgsm pl22), the new
  full decoder wrapper with decoder homing, an encoder homing function, and
  new stateless frame packing and unpacking functions.

libgsmfrp change history: version 1.0.1 to version 1.0.2
========================================================

There are only two changes, both involving corner cases with invalid SID frames
being received:

1) An invalid SID frame was received immediately following a good speech frame.
   In this case we start CN generation, but we take the needed LARc and Xmaxc
   parameters from the last speech frame, instead of the usual procedure of
   extracting them from a valid SID frame.  The change from 1.0.1 to 1.0.2
   concerns the Xmaxc parameter in this corner case: in 1.0.1 we took Xmaxc
   from the last subframe and used it for ensuing CN generation, but in 1.0.2
   we compute a more proper mean Xmaxc from all 4 subframes, by dequantizing,
   summing and requantizing.

2) An invalid SID frame was received in the speech muting state.  The sequence
   of inputs would have to be:

   - a good speech frame;
   - one or more BFIs, but not too many, so that the cached speech frame
     does not decay fully by Xmaxc reduction;
   - an invalid SID frame.

   In version 1.0.1 we handled this even more obscure corner case by entering
   the CN muting state, i.e., the state that is normally entered upon the
   second lost SID.  In version 1.0.2 we ignore invalid SID in the speech
   muting state and act as if we got BFI, i.e., continue speech muting rather
   than switch to CN muting.

libgsmfrp change history: version 1.0.0 to version 1.0.1
========================================================

Version 1.0.0 exhibited the following defects, which are fixed in 1.0.1:

1) The last received valid SID was cached forever for the purpose of
   handling future invalid SIDs - we could have received some valid
   SID ages ago, then lots of speech or NO_DATA, and if we then get
   an invalid SID, we would resurrect the last valid SID from ancient
   history - a bad design.  In our new design, we handle invalid SID
   based on the current state, much like BFI.

2) GSM 06.11 spec says clearly that after the second lost SID
   (received BFI=1 && TAF=1 in CN state) we need to gradually decrease
   the output level, rather than jump directly to emitting silence
   frames - we previously failed to implement such logic.

3) Per GSM 06.12 section 5.2, Xmaxc should be the same in all 4 subframes
   in a SID frame.  What should we do if we receive an otherwise valid
   SID frame with different Xmaxc?  Our previous approach would
   replicate this Xmaxc oddity in every subsequent generated CN frame,
   which is rather bad.  In our new design, the very first CN frame
   (which can be seen as a transformation of the SID frame itself)
   retains the original 4 distinct Xmaxc, but all subsequent CN frames
   are based on the Xmaxc from the last subframe of the most recent SID.