gsm-codec-lib: doc/FR1-Rx-DTX annotate

annotate doc/FR1-Rx-DTX @ 266:8821ffaa93a5

libgsmfr2: integrate decoder main function from libgsm

author	Mychaela Falconia <falcon@freecalypso.org>
date	Sun, 14 Apr 2024 00:36:16 +0000
parents	731c98b67da1
children	4034c2b06ec8

rev	line source
135 22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 At the level of provided functionality and architectural structure, ETSI GSM
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 specifications for DTX (discontinuous transmission) are very symmetric between
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	3 FR and EFR: the same DTX functionality is specified for both codecs, with the
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	4 same overall architecture. However, there is one important difference: in the
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	5 case of EFR the complete implementation of all DTX functions (for both Tx and
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	6 Rx) forms an integral and inseparable part of the reference codec (implemented
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	7 in C) from the beginning, whereas in the case of FR1 the addition of DTX is
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	8 somewhat of an afterthought. GSM 06.10 defines a "pure" FR codec without any
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	9 DTX functions, and this most basic spec can be and has been implemented in this
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	10 "pure" form - classic Unix libgsm from 1990s is a proper, fully compliant
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	11 implementation of GSM 06.10, but only this spec, without any DTX. In contrast,
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	12 there has never existed a "pure" implementation of GSM 06.60 EFR codec without
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	13 associated Tx and Rx DTX functions. Furthermore, there is an important
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	14 distinction between Tx and Rx DTX handlers for FR1:
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	15
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	16 * Anyone who seeks to implement Tx DTX for FR1 would have to dig into the guts
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	17 of GSM 06.10 encoder and augment it with VAD and SID encoding functions per
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	18 GSM 06.32 and 06.12 specs.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	19
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	20 * In contrast, the Rx DTX handler for FR1 is modular: the way it is specified
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	21 in GSM 06.11, 06.12 and 06.31 is a front-end to unmodified GSM 06.10 decoder.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	22 On the Rx side, the interface from the radio subsystem to the Rx DTX handler
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	23 consists of 260 bits of frame plus BFI and TAF flags (the spec also defines a
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	24 SID flag, but it is determined from frame payload bits), and then the
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	25 interface from the Rx DTX handler to the GSM 06.10 decoder is another FR frame
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	26 of 260 bits.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	27
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28 What are the implications of this situation for the GSM published-source
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	29 software community? Prior to the present libgsmfrp offering, there has always
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	30 been libgsm, but no Rx DTX handler. If you are working with a GSM uplink RTP
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31 stream from a BTS or a GSM downlink frame stream read out of TI Calypso DSP or
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	32 some other GSM MS PHY, feeding that stream directly to libgsm (without passing
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	33 through an Rx DTX handler) is NOT acceptable: a "bare" GSM 06.10 decoder won't
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	34 recognize SID frames and won't produce the expected comfort noise output, and
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	35 what are you going to do in those 20 ms windows in which no good traffic frame
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	36 was received? The situation becomes especially bad (unkind on ears) if you are
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	37 reading received downlink frames out of TI Calypso DSP: the DSP's buffer will
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	38 have some bit content in every 20 ms window, but naturally this bit content
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	39 will be garbage during those frame windows when no good frame was received;
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	40 feeding that garbage to libgsm produces noises that are very unkind on ears.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	41
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	42 The correct solution is to implement an Rx DTX handler, pass the stream of
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	43 frames and flags from the BTS or the MS PHY to this handler first, and then pass
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	44 the output of this handler to libgsm 06.10 decoder. Themyscira libgsmfrp is a
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	45 Free Software implementation of Rx DTX handler for GSM FR, implementing SID
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	46 classification, comfort noise generation and error concealment.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	47
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	48 Effect of extra preprocessing
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	49 =============================
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	50
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	51 One key detail deserves extra emphasis before going into library API details:
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	52 if the input to libgsmfrp consists entirely of good speech frames (no SID frames
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	53 and no BFIs), then the preprocessor becomes an identity transform. Therefore,
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	54 if the output of our libgsmfrp preprocessor were to be fed to an additional
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	55 instance of the same further down the processing chain, no extra transformation
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	56 of any kind will happen.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	57
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	58 Using libgsmfrp
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	59 ===============
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	60
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	61 The external public interface to Themyscira libgsmfrp consists of a single
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	62 header file <gsm_fr_preproc.h>; it should be installed in the same system
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	63 include directory as <gsm.h> from libgsm. Please note that <gsm_fr_preproc.h>
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	64 includes <gsm.h>, as needed for gsm_byte and gsm_frame defined types.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	65
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	66 The dialect of C we chose for libgsmfrp is ANSI C (function prototypes), const
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	67 qualifier is used where appropriate; however, unlike libgsmefr, the interface
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	68 to libgsmfrp is defined in terms of gsm_byte type defined in <gsm.h>, included
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	69 from <gsm_fr_preproc.h>.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	70
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	71 State allocation and freeing
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	72 ============================
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	73
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	74 The Rx DTX handler is stateful, hence you will need to allocate a preprocessor
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	75 state structure in addition to the usual libgsm state structure for your GSM FR
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	76 Rx session. The necessary function is:
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	77
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	78 extern struct gsmfr_preproc_state *gsmfr_preproc_create(void);
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	79
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	80 struct gsmfr_preproc_state is an opaque structure to library users: you only get
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	81 a pointer which you remember and pass around, but <gsm_fr_preproc.h> does not
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	82 give you a full definition of this struct. As a library user, you don't even
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	83 get to know the size of this struct, hence the necessary malloc() operation
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	84 happens inside gsmfr_preproc_create(). However, the structure is malloc'ed as
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	85 a single chunk, hence when you are done with it, simply call free() on the
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	86 pointer you got from gsmfr_preproc_create().
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	87
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	88 gsmfr_preproc_create() can fail if the malloc() call inside fails, in which case
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	89 it returns NULL.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	90
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	91 Preprocessing good frames
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	92 =========================
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	93
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	94 For every good traffic frame (BFI=0) you receive from the radio subsystem, you
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	95 need to call this preprocessor function:
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	96
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	97 extern void gsmfr_preproc_good_frame(struct gsmfr_preproc_state *state,
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	98 gsm_byte *frame);
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	99
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	100 The second argument is both input and output, i.e., the frame is modified in
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	101 place. If the received frame is not SID (specifically, if the SID field
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	102 deviates from the SID codeword by 16 or more bits, per GSM 06.31 section 6.1.1),
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	103 then the frame (considered a good speech frame) will be left unmodified (i.e.,
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	104 it is to be passed unchanged to the GSM 06.10 decoder), but preprocessor state
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	105 will be updated. OTOH, if the received frame is classified as either valid or
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	106 invalid SID per GSM 06.31, then the output frame will contain comfort noise
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	107 generated by the preprocessor using a PRNG, or a silence frame in one particular
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	108 corner case.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	109
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	110 GSM-FR RTP (or libgsm) 0xD magic: the upper nibble of the first byte can be
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	111 anything on input to gsmfr_preproc_good_frame(), but the output frame will
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	112 always have the correct magic in it.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	113
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	114 Handling BFI conditions
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	115 =======================
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	116
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	117 If you received a lost/missing frame indication instead of a good traffic frame,
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	118 call this preprocessor function:
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	119
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	120 extern void gsmfr_preproc_bfi(struct gsmfr_preproc_state *state, int taf,
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	121 gsm_byte *frame_out);
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	122
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	123 TAF is a flag defined in GSM 06.31 section 6.1.1; if you don't have this flag,
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	124 pass 0 - you will lose the function of comfort noise muting in the event of
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	125 prolonged SID loss, but all other Rx DTX functions will still work the same.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	126
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	127 With this function the 33-byte frame buffer is only an output, i.e., prior
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	128 buffer content is a don't-care and there is no provision for making any use of
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	129 erroneous frames like in EFR. The frame generated by the preprocessor may be
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	130 substitution/muting, comfort noise or silence depending on the state.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	131
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	132 Other miscellaneous functions
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	133 =============================
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	134
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	135 extern void gsmfr_preproc_reset(struct gsmfr_preproc_state *state);
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	136
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	137 This function resets the preprocessor state to what it is right out of
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	138 gsmfr_preproc_create(), which is naturally just a combination of malloc() and
159 aa4cdab30dc8 doc/FR1-Rx-DTX: typo fix Mychaela Falconia <falcon@freecalypso.org> parents: 135 diff changeset	139 gsmfr_preproc_reset(). Given that our Rx DTX handler state is much simpler
135 22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	140 than, for example, EFR codec state, there does not seem to be any need for
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	141 explicit resets, but the reset function is made public for the sake of
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	142 completeness.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	143
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	144 extern int gsmfr_preproc_sid_classify(const gsm_byte *frame);
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	145
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	146 This function analyzes an RTP-encoded FR frame (the upper nibble of the first
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	147 byte is NOT checked for 0xD signature) for the SID codeword of GSM 06.12 and
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	148 classifies the frame as SID=0, SID=1 or SID=2 per the rules of GSM 06.31
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	149 section 6.1.1.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	150
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	151 Silence frame datum
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	152 ===================
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	153
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	154 extern const gsm_frame gsmfr_preproc_silence_frame;
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	155
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	156 Many implementors make the mistake of thinking that a GSM FR silence frame is a
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	157 frame of 260 zero bits, but the official specs disagree: the silence frame given
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	158 in GSM 06.11 (3GPP TS 46.011, at the very end of the spec) is quite different.
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	159 Themyscira libgsmfrp implements the correct silence frame per the spec, and that
22601ae99434 doc/FR1-Rx-DTX article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	160 datum is also made public.
244 fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	161
250 731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	162 libgsmfrp change history: version 1.0.1 to version 1.0.2
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	163 ========================================================
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	164
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	165 There are only two changes, both involving corner cases with invalid SID frames
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	166 being received:
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	167
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	168 1) An invalid SID frame was received immediately following a good speech frame.
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	169 In this case we start CN generation, but we take the needed LARc and Xmaxc
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	170 parameters from the last speech frame, instead of the usual procedure of
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	171 extracting them from a valid SID frame. The change from 1.0.1 to 1.0.2
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	172 concerns the Xmaxc parameter in this corner case: in 1.0.1 we took Xmaxc
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	173 from the last subframe and used it for ensuing CN generation, but in 1.0.2
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	174 we compute a more proper mean Xmaxc from all 4 subframes, by dequantizing,
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	175 summing and requantizing.
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	176
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	177 2) An invalid SID frame was received in the speech muting state. The sequence
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	178 of inputs would have to be:
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	179
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	180 - a good speech frame;
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	181 - one or more BFIs, but not too many, so that the cached speech frame
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	182 does not decay fully by Xmaxc reduction;
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	183 - an invalid SID frame.
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	184
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	185 In version 1.0.1 we handled this even more obscure corner case by entering
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	186 the CN muting state, i.e., the state that is normally entered upon the
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	187 second lost SID. In version 1.0.2 we ignore invalid SID in the speech
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	188 muting state and act as if we got BFI, i.e., continue speech muting rather
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	189 than switch to CN muting.
731c98b67da1 doc/FR1-Rx-DTX: document changes from 1.0.1 to 1.0.2 Mychaela Falconia <falcon@freecalypso.org> parents: 244 diff changeset	190
244 fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	191 libgsmfrp change history: version 1.0.0 to version 1.0.1
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	192 ========================================================
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	193
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	194 Version 1.0.0 exhibited the following defects, which are fixed in 1.0.1:
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	195
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	196 1) The last received valid SID was cached forever for the purpose of
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	197 handling future invalid SIDs - we could have received some valid
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	198 SID ages ago, then lots of speech or NO_DATA, and if we then get
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	199 an invalid SID, we would resurrect the last valid SID from ancient
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	200 history - a bad design. In our new design, we handle invalid SID
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	201 based on the current state, much like BFI.
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	202
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	203 2) GSM 06.11 spec says clearly that after the second lost SID
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	204 (received BFI=1 && TAF=1 in CN state) we need to gradually decrease
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	205 the output level, rather than jump directly to emitting silence
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	206 frames - we previously failed to implement such logic.
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	207
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	208 3) Per GSM 06.12 section 5.2, Xmaxc should be the same in all 4 subframes
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	209 in a SID frame. What should we do if we receive an otherwise valid
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	210 SID frame with different Xmaxc? Our previous approach would
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	211 replicate this Xmaxc oddity in every subsequent generated CN frame,
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	212 which is rather bad. In our new design, the very first CN frame
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	213 (which can be seen as a transformation of the SID frame itself)
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	214 retains the original 4 distinct Xmaxc, but all subsequent CN frames
fcc0887ff0d0 doc/FR1-Rx-DTX: document changes from 1.0.0 to 1.0.1 Mychaela Falconia <falcon@freecalypso.org> parents: 159 diff changeset	215 are based on the Xmaxc from the last subframe of the most recent SID.

FreeCalypso > hg > gsm-codec-lib

annotate doc/FR1-Rx-DTX @ 266:8821ffaa93a5