FreeCalypso > hg > gsm-codec-lib

annotate doc/TFO-transform @ 553:ebcf414b7d99

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/TFO-transform: describe details for FRv1, both modes
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 07 Oct 2024 08:24:24 +0000
parents 8f44d7064c56
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
551
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
1 TFO transform: general definition and goal
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
2 ==========================================
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
3
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
4 "TFO transform" is the term adopted by Themyscira Wireless for the non-trivial
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
5 transform on GSM codec frames called for by the TFO spec, 3GPP TS 28.062
551
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
6 section C.3.2.1.1. We have a goal of implementing TFO transform for all 3
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
7 classic GSM codecs (FR, HR and EFR) in our Themyscira codec libraries; in the
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
8 present release, only GSM-FR version has been implemented.
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
9
551
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
10 The input to this transform is the stream of received uplink frames from call
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
11 leg A, possibly containing BFI frame gaps and SID frames if call leg A uses
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
12 DTXu. The output from the transform is a "pristine" stream of good codec frames
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
13 to be transmitted on the radio downlink for call leg B: good speech frames only
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
14 in the non-DTXd case, or a mixture of good speech and valid SID frames with
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
15 DTXd. TFO transform is expected to be an identity transform when the input is
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
16 100% good speech frames, but it becomes non-trivial when it has to insert
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
17 synthetic "speech" frames for comfort noise or as error concealment.
535
bf7bbc7d494f doc/FR1-library-API: document new additions
Mychaela Falconia <falcon@freecalypso.org>
parents: 299
diff changeset
18
551
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
19 TFO transform for FRv1
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
20 ======================
536
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_*
Mychaela Falconia <falcon@freecalypso.org>
parents: 535
diff changeset
21
551
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
22 This transform is implemented in libgsmfr2 in both DTXd=0 and DTXd=1
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
23 configurations. DTXd=0 version of FRv1 TFO transform is mostly identical with
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
24 the Rx DTX handler preprocessor stage of regular speech decoding (the only
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
25 difference is in details of the in-band homing function); DTXd=1 version is
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
26 specific to this TFO/TrFO application.
298
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
27
551
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
28 In addition to libgsmfr2 functions documented in FR1-library-API article, there
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
29 is a command line test program that exercises our implementation of this TFO
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
30 transform. Its usage is:
298
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
31
551
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
32 gsmfr-tfo-xfrm [-d] input.hex output.hex
298
a45f806cada9 doc/FR1-library-API: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 297
diff changeset
33
551
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
34 Both input and output files are in TW-TS-005 Annex A hexadecimal format. The
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
35 input will typically consist of TW-TS-001 extended RTP format, whereas the
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
36 output is always emitted in the basic format, pure GSM-FR codec frames only.
299
59751c8fc773 doc/FR1-library-API: finish in first pass
Mychaela Falconia <falcon@freecalypso.org>
parents: 298
diff changeset
37
551
8f44d7064c56 document gsmfr-tfo-xfrm
Mychaela Falconia <falcon@freecalypso.org>
parents: 536
diff changeset
38 -d option enables DTXd, which is disabled by default.
553
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
39
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
40 Details of FRv1 TFO transform with DTXd=0
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
41 -----------------------------------------
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
42
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
43 Our implementation of TFO transform in DTXd=0 configuration is mostly identical
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
44 with the Rx DTX handler preprocessor stage of regular speech decoding; the
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
45 details are covered in FR1-Rx-DTX-detail article.
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
46
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
47 ThemWi implementation of TFO transform includes the feature of in-band homing:
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
48 if the input to the transform is the spec-defined decoder homing frame (DHF),
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
49 this DHF is passed through to the output just like any other good speech frame,
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
50 but the internal state is reset to the initial "home" state.
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
51
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
52 Details of FRv1 TFO transform with DTXd=1
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
53 -----------------------------------------
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
54
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
55 We implement the DTXd=1 version of TFO transform as a post-processor stage
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
56 after executing the "regular" logic for DTXd=0 case; more precisely, our
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
57 "regular" Rx DTX handler code sets some flags that are only used by the TFO
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
58 DTXd=1 post-processor, and the latter element acts on one of those flags.
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
59
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
60 The resulting visible behaviour of our TFO transform is as follows:
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
61
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
62 * Whenever a valid SID frame comes in, it is re-emitted on the output in the
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
63 same frame position with the same parameters, even if it has different Xmaxc
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
64 in different subframes. However, it is "rejuvenated" in that any possible
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
65 single bit error in the SID codeword is corrected, and all unused bits are
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
66 also cleared. This behaviour agrees with GSM 08.62 section 8.2.2.
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
67
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
68 * Also in agreement with GSM 08.62 section 8.2.2, any unusable frames or invalid
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
69 SID frames that come in after that valid SID (but before that cached SID
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
70 expires by way of two lost SID events, or a good speech frame ends the DTX
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
71 pause) are replaced with output that repeats the last processed valid SID.
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
72 This output consists of repeated SID frames just like the original, but with
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
73 all 4 Xmaxc parameters set to the one from the last subframe.
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
74
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
75 * If an invalid SID frame is received directly after good speech, indicating a
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
76 need to start comfort noise insertion but lacking usable parameters for it,
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
77 the output from the TFO transform is just like that described in
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
78 FR1-Rx-DTX-detail article, but in the form of SID frames rather than "speech"
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
79 frames that represent CN.
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
80
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
81 * If two consecutive lost SID events occur and the Rx DTX handler has to enter
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
82 CN muting state, our TFO transform breaks out of DTX and emits the CN muting
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
83 sequence as "speech" frames rather than altered SID. This tactic is done in
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
84 order to produce immediate effect on the receiving end. Once the muting fully
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
85 decays, the transform emits 4 silence frames of GSM 06.11 Table 1, then
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
86 switches to endlessly emitting SIDs derived from this silence frame (same
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
87 LARc, Xmaxc=0).
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
88
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
89 * Any other time the Rx DTX handler is in NO_DATA state (initial reset state or
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
90 fully decayed state after speech muting), the TFO transform in DTXd=1 mode
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
91 emits SIDs derived from the silence frame instead of actual silence frames.
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
92
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
93 Emission of transform-synthesized SIDs frames during muting states is done in
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
94 order to help achieve the presumed network operator's goal of DTX maximization
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
95 and radio interference reduction. However, if the input to the transform is
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
96 all good speech frames without DTX pauses, the transform does not attempt to
ebcf414b7d99 doc/TFO-transform: describe details for FRv1, both modes
Mychaela Falconia <falcon@freecalypso.org>
parents: 551
diff changeset
97 apply VAD and make its own DTXd.