# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1728110924 0
# Node ID 8f44d7064c563e04a57b64f9d8f4dd50da87c425
# Parent  de333989a12b06b88a6c91722bf72775bb8c314b
document gsmfr-tfo-xfrm

diff -r de333989a12b -r 8f44d7064c56 doc/TFO-transform
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/TFO-transform	Sat Oct 05 06:48:44 2024 +0000
@@ -0,0 +1,38 @@
+TFO transform: general definition and goal
+==========================================
+
+"TFO transform" is the term adopted by Themyscira Wireless for the non-trivial
+transform on GSM codec frames called for by the TFO spec, 3GPP TS 28.062
+section C.3.2.1.1.  We have a goal of implementing TFO transform for all 3
+classic GSM codecs (FR, HR and EFR) in our Themyscira codec libraries; in the
+present release, only GSM-FR version has been implemented.
+
+The input to this transform is the stream of received uplink frames from call
+leg A, possibly containing BFI frame gaps and SID frames if call leg A uses
+DTXu.  The output from the transform is a "pristine" stream of good codec frames
+to be transmitted on the radio downlink for call leg B: good speech frames only
+in the non-DTXd case, or a mixture of good speech and valid SID frames with
+DTXd.  TFO transform is expected to be an identity transform when the input is
+100% good speech frames, but it becomes non-trivial when it has to insert
+synthetic "speech" frames for comfort noise or as error concealment.
+
+TFO transform for FRv1
+======================
+
+This transform is implemented in libgsmfr2 in both DTXd=0 and DTXd=1
+configurations.  DTXd=0 version of FRv1 TFO transform is mostly identical with
+the Rx DTX handler preprocessor stage of regular speech decoding (the only
+difference is in details of the in-band homing function); DTXd=1 version is
+specific to this TFO/TrFO application.
+
+In addition to libgsmfr2 functions documented in FR1-library-API article, there
+is a command line test program that exercises our implementation of this TFO
+transform.  Its usage is:
+
+gsmfr-tfo-xfrm [-d] input.hex output.hex
+
+Both input and output files are in TW-TS-005 Annex A hexadecimal format.  The
+input will typically consist of TW-TS-001 extended RTP format, whereas the
+output is always emitted in the basic format, pure GSM-FR codec frames only.
+
+-d option enables DTXd, which is disabled by default.
diff -r de333989a12b -r 8f44d7064c56 doc/Utils-overview
--- a/doc/Utils-overview	Sat Oct 05 02:16:48 2024 +0000
+++ b/doc/Utils-overview	Sat Oct 05 06:48:44 2024 +0000
@@ -70,6 +70,8 @@
 
 gsmfr-preproc		See FR1-Rx-DTX article.
 
+gsmfr-tfo-xfrm		See TFO-transform article.
+
 gsmrec-dump		See Binary-file-format article.
 
 gsmx-to-tw5a		See TW-TS-005 article.