--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/FR1-library-history	Mon Apr 15 18:36:21 2024 +0000
@@ -0,0 +1,74 @@
+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.
+
+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.