FreeCalypso > hg > gsm-codec-lib

comparison doc/EFR-library-API @ 161:fe5aceaf51e0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/EFR-library-API: document new handling of BFI with no data
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 15 Dec 2022 19:21:45 +0000
parents 1c529bb31219
children 9208db14b4b9
comparison
equal deleted inserted replaced
160:eefef9f6d533 161:fe5aceaf51e0
70 decoder) and BFI and TAF flags defined in GSM 06.81 section 6.1.1. Note the 70 decoder) and BFI and TAF flags defined in GSM 06.81 section 6.1.1. Note the
71 absence of a SID flag argument: EFR_decode_frame() calls our own utility 71 absence of a SID flag argument: EFR_decode_frame() calls our own utility
72 function EFR_sid_classify() to determine SID from the frame itself per the rules 72 function EFR_sid_classify() to determine SID from the frame itself per the rules
73 of GSM 06.81 section 6.1.1. 73 of GSM 06.81 section 6.1.1.
74 74
75 Many EFR decoder applications will also be faced with a situation where they 75 The canonical EFR decoder always expects frame bits input to be present, even
76 receive a frame gap (no data at all), and they need to run the EFR decoder with 76 during BFI condtions! More specifically, if a BFI=1 decoding call comes in when
77 BFI=1, but don't have any frame-bits input. If you find yourself in this 77 the decoder is in comfort noise generation state (after a SID), then all frame
78 situation, call the following function: 78 bits passed along with BFI=1 are ignored as one would naturally expect for
79 frames that typically aren't transmitted at all - but if a BFI=1 decoding call
80 comes in when the decoder is in regular speech mode, the canonical decoder will
81 use the "fixed codebook excitation pulses" part of the erroneous frame (one
82 declared to be garbage) as part of its decoding operation! (This part
83 constitutes 35 bits per subframe or 140 bits out of 244 per frame.)
84
85 BFI with no data
86 ================
87
88 Many EFR decoder applications will be faced with a situation where they receive
89 a frame gap (no data at all), and they need to run the EFR decoder with BFI=1 -
90 but the application doesn't have any frame-bits input. Yet the canonical EFR
91 decoder requires *some* erroneous frame bits to be fed to it - so what gives?
92 Our initial approach was to feed the decoder all zeros in the place of codec
93 parameters - but further analysis reveals that approach to be bad. (To see for
94 yourself, study the code in d1035pf.c and think what it will do when the input
95 is fixed at all zeros.) Our new approach is to generate pseudorandom bits for
96 these pulse parameters, as detailed below.
97
98 If you find yourself in the situation of needing to feed BFI=1 with no frame
99 data bits to the decoder, call the following function in the place of
100 EFR_decode_frame():
79 101
80 extern void EFR_decode_bfi_nodata(struct EFR_decoder_state *st, int taf, 102 extern void EFR_decode_bfi_nodata(struct EFR_decoder_state *st, int taf,
81 int16_t *pcm); 103 int16_t *pcm);
82 104
83 EFR_decode_bfi_nodata() is equivalent to calling EFR_decode_frame() with a frame 105 This function begins by checking the internal state flag RX_SP_FLAG, indicating
84 buffer of 31 zero bytes (or 0xC signature followed by 244 zero bits) and BFI=1, 106 whether the decoder is in speech or comfort noise generation mode. If
85 but is slightly more efficient in that the internal steps of EFR_frame2params() 107 RX_SP_FLAG is set, indicating speech state, then the main body of the decoder
86 and EFR_sid_classify() are skipped, and the made-up "frame" of 244 zero bits is 108 will be making use of fixed codebook pulse parameters even for erroneous frames,
87 passed to the decoder core at the params array level. 109 and EFR_decode_bfi_nodata() will invoke a PRNG to fill in pseudorandom bits.
88 110 If RX_SP_FLAG is clear, then the decoder is generating comfort noise following
89 Note that the official EFR decoder from ETSI, which we've replicated in our 111 reception of a SID, and BFI conditions are fully expected because the
90 librified form in libgsmefr, does make use of some presumed-invalid frame data 112 transmitter is expected to be off. In this case EFR_decode_bfi_nodata() feeds
91 bits under BFI=1 conditions: see the description in GSM 06.61 section 6.1, where 113 all-zeros parameters to the main body of the decoder, as none of them will be
92 the last sentence reads "The received fixed codebook excitation pulses from the 114 used.
93 erroneous frame are always used as such." With our current implementation, the
94 "erroneous frame" in the case of completely lost or missing frames is a made-up
95 frame of 244 zero bits; the question of whether this approach is good enough or
96 if we need to do something more complex remains for further study.
97 115
98 Stateless utility functions 116 Stateless utility functions
99 =========================== 117 ===========================
100 118
101 All functions in this section are stateless (no encoder state or decoder state 119 All functions in this section are stateless (no encoder state or decoder state