FreeCalypso > hg > gsm-codec-lib

annotate doc/TFO-transform @ 585:3c6bf0d26ee7 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
TW-TS-005 reader: fix maximum line length bug TW-TS-005 section 4.1 states: The maximum allowed length of each line is 80 characters, not including the OS-specific newline encoding. The implementation of this line length limit in the TW-TS-005 hex file reader function in the present suite was wrong, such that lines of the full maximum length could not be read. Fix it. Note that this bug affects comment lines too, not just actual RTP payloads. Neither Annex A nor Annex B features an RTP payload format that goes to the maximum of 40 bytes, but if a comment line goes to the maximum allowed length of 80 characters not including the terminating newline, the bug will be triggered, necessitating the present fix.
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 25 Feb 2025 07:49:28 +0000
parents ebcf414b7d99
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.