gsm-codec-lib: doc/FR1-library-API annotate

annotate doc/FR1-library-API @ 585:3c6bf0d26ee7 default tip

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	a3300483ae74
children

rev	line source
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 Libgsmfr2 general usage
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 =======================
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	3
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	4 The external public interface to Themyscira libgsmfr2 consists of a single
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	5 header file <tw_gsmfr.h>; it should be installed in some system include
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	6 directory.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	7
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	8 The dialect of C used by all Themyscira GSM codec libraries is ANSI C (function
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	9 prototypes), const qualifier is used where appropriate, and the interface is
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	10 defined in terms of <stdint.h> types; <tw_gsmfr.h> includes <stdint.h>. The
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	11 use of old libgsm defined types (gsm_byte, gsm_frame and gsm_signal) has been
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	12 abolished in the migration from libgsm+libgsmfrp to libgsmfr2.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	13
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	14 GSM 06.10 encoder and decoder
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	15 =============================
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	16
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	17 Both the encoder and the decoder are stateful; each running instance of either
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	18 element needs its own state structure. However, this GSM 06.10 component of
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	19 libgsmfr2 shares a peculiar property with old libgsm from which it was derived:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	20 the same state structure (struct gsmfr_0610_state) is used by both entities.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	21 Needless to say, each given instance of struct gsmfr_0610_state must be used
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	22 for only one purpose, either for the encoder or for the decoder; mixing calls
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	23 to encoder and decoder functions with the same state structure is an invalid
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	24 operation with undefined results.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	25
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	26 State structures for the basic encoder or decoder are allocated with this
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	27 function:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	29 struct gsmfr_0610_state *gsmfr_0610_create(void);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	30
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31 This function allocates dynamic memory for the state structure with malloc()
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	32 and returns a pointer to the allocated and initialized struct if successful, or
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	33 NULL if malloc() fails. The state structure is malloc'ed as a single chunk,
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	34 hence when you are done with it, simply free() it.
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	35
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	36 The initialization or reset portion of gsmfr_0610_create() operation can always
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	37 be repeated with this function:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	38
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	39 void gsmfr_0610_reset(struct gsmfr_0610_state *state);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	40
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	41 To support applications that need (or prefer) to use some different method of
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	42 managing their memory allocations, the library also exports this const datum:
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	43
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	44 extern const unsigned gsmfr_0610_state_size;
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	45
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	46 Using this feature, one can replace gsmfr_0610_create() with something like the
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	47 following (example for applications based on Osmocom libraries):
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	48
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	49 struct gsmfr_0610_state *st;
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	50 st = talloc_size(ctx, gsmfr_0610_state_size);
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	51 if (st)
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	52 gsmfr_0610_reset(st);
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	53
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	54 Immediately after gsmfr_0610_create() or gsmfr_0610_reset(), the "virgin" state
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	55 structure can be used either for the encoder or for the decoder; however, once
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	56 that state struct has been passed to functions of either group, it can only be
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	57 used for that functional group.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	58
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	59 Encoder specifics
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	60 -----------------
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	61
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	62 The most elementary single-frame processing function of libgsmfr2 GSM 06.10
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	63 encoder is:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	64
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	65 void gsmfr_0610_encode_params(struct gsmfr_0610_state st, const int16_t pcm,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	66 struct gsmfr_param_frame *param);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	67
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	68 The input is an array of 160 linear PCM samples (left-justified in int16_t),
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	69 and the output is this structure:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	70
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	71 struct gsmfr_param_frame {
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	72 int16_t LARc[8];
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	73 int16_t Nc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	74 int16_t bc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	75 int16_t Mc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	76 int16_t xmaxc[4];
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	77 int16_t xMc[4][13];
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	78 };
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	79
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	80 Most of the time the following wrapper function is more useful:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	81
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	82 void gsmfr_0610_encode_frame(struct gsmfr_0610_state st, const int16_t pcm,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	83 uint8_t *frame);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	84
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	85 The output is a 33-byte buffer, filled with the encoded GSM-FR speech frame in
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	86 the RTP format specified in ETSI TS 101 318 and IETF RFC 3551.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	87
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	88 If the optional encoder homing feature is desired, call this function right
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	89 after the call to gsmfr_0610_encode_frame() or gsmfr_0610_encode_params():
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	90
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	91 void gsmfr_0610_encoder_homing(struct gsmfr_0610_state st, const int16_t pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	92
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	93 This function checks to see if the PCM frame (160 linear PCM samples) is an EHF;
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	94 if the input frame is indeed EHF, the function calls gsmfr_0610_reset().
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	95
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	96 Decoder specifics
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	97 -----------------
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	98
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	99 The internal native form of the 06.10 decoder once again uses
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	100 struct gsmfr_param_frame:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	101
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	102 void gsmfr_0610_decode_params(struct gsmfr_0610_state *st,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	103 const struct gsmfr_param_frame *param,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	104 int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	105
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	106 The more commonly used RTP-format version is:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	107
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	108 void gsmfr_0610_decode_frame(struct gsmfr_0610_state st, const uint8_t frame,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	109 int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	110
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	111 Please note:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	112
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	113 1) The basic GSM 06.10 decoder is just that: there is no SID recognition or DTX
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	114 handling, every possible input bit pattern will be interpreted and decoded
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	115 as a GSM 06.10 speech frame.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	116
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	117 2) There is no decoder homing function at this layer, and no check for DHF.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	118
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	119 3) The RTP signature nibble 0xD is ignored (not checked) by
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	120 gsmfr_0610_decode_frame().
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	121
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	122 Rx DTX preprocessor block
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	123 =========================
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	124
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	125 The Rx DTX preprocessor is its own stateful element, independent from the 06.10
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	126 decoder to which it is usually coupled. Libgsmfr2 provides a "fulldec" wrapper
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	127 that incorporates both elements, but the ability to use the Rx DTX preprocessor
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	128 by itself still remains, unchanged from our previous libgsmfrp offering. One
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	129 significant application for this preprocessor by itself, without immediately
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	130 following it with the GSM 06.10 decode step, is the TFO/TrFO transform of 3GPP
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	131 TS 28.062 section C.3.2.1.1 for GSM-FR: our Rx DTX preprocessor does exactly
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	132 what that section calls for, specifically in "case 1" where the input UL frame
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	133 stream may contain SIDs and BFI frame gaps, but the output must be 100% valid
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	134 frames and SID-free. The current version of libgsmfr2 includes some additional
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	135 provisions for using our preprocessor block as a TFO transform in both non-DTXd
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	136 and DTXd-enabled configurations, as detailed in a later section of this
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	137 document.
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	138
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	139 The state structure for this block is struct gsmfr_preproc_state, and it is
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	140 allocated with this function:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	141
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	142 struct gsmfr_preproc_state *gsmfr_preproc_create(void);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	143
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	144 Like other state structures in Themyscira GSM codec libraries, this opaque
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	145 state is malloc'ed as a single chunk and can be simply freed afterward. A
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	146 reset function is also provided:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	147
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	148 void gsmfr_preproc_reset(struct gsmfr_preproc_state *state);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	149
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	150 There is also a public const datum with the size of this structure, allowing
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	151 use of talloc and other alternative schemes:
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	152
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	153 extern const unsigned gsmfr_preproc_state_size;
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	154
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	155 Preprocessing good frames
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	156 -------------------------
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	157
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	158 For every good traffic frame (BFI=0) you receive from the radio subsystem, you
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	159 need to call this preprocessor function:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	160
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	161 void gsmfr_preproc_good_frame(struct gsmfr_preproc_state *state,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	162 uint8_t *frame);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	163
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	164 The second argument is both input and output, i.e., the frame is modified in
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	165 place. If the received frame is not SID (specifically, if the SID field
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	166 deviates from the SID codeword by 16 or more bits, per GSM 06.31 section 6.1.1),
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	167 then the frame (considered a good speech frame) will be left unmodified (i.e.,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	168 it is to be passed unchanged to the GSM 06.10 decoder), but preprocessor state
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	169 will be updated. OTOH, if the received frame is classified as either valid or
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	170 invalid SID per GSM 06.31, then the output frame will contain comfort noise
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	171 generated by the preprocessor using a PRNG, or a speech muting or silence frame
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	172 in some corner cases involving invalid SID.
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	173
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	174 GSM-FR RTP (originally libgsm) 0xD magic: the upper nibble of the first byte
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	175 can be anything on input to gsmfr_preproc_good_frame(), but the output frame
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	176 will always have the correct magic in it.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	177
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	178 There is also a variant of this function (implemented as a wrapper) that applies
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	179 homing logic:
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	180
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	181 void gsmfr_preproc_good_frame_hm(struct gsmfr_preproc_state *state,
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	182 uint8_t *frame);
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	183
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	184 This function operates just like plain gsmfr_preproc_good_frame() except for
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	185 one difference: if the input matches the decoder homing frame (DHF), the state
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	186 is reset with an internal call to gsmfr_preproc_reset(). (Because the DHF is
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	187 still a good speech frame, it is always passed through to the output unchanged
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	188 by both functions - the only difference is the effect on subsequent state.)
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	189 The homing version of good frame preproc is intended for TFO applications, and
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	190 is invoked internally by gsmfr_tfo_xfrm_main() function described in a later
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	191 section of this document.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	192
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	193 Handling BFI conditions
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	194 -----------------------
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	195
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	196 If you received a lost/missing frame indication instead of a good traffic frame,
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	197 call one of these preprocessor functions:
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	198
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	199 void gsmfr_preproc_bfi(struct gsmfr_preproc_state *state, int taf,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	200 uint8_t *frame_out);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	201
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	202 or
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	203
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	204 void gsmfr_preproc_bfi_bits(struct gsmfr_preproc_state *state,
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	205 const uint8_t *bad_frame, int taf,
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	206 uint8_t *frame_out);
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	207
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	208 gsmfr_preproc_bfi_bits() should be called if you received payload bits along
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	209 with the BFI flag; plain gsmfr_preproc_bfi() should be called if you received
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	210 BFI with no data. The bad frame passed to gsmfr_preproc_bfi_bits() is used
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	211 only to check if the BFI should be handled as an invalid SID rather than the
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	212 more common case of an unusable frame - see GSM 06.31 for definitions of these
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	213 terms. Past the SID check, the bad frame content is a don't-care, and there is
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	214 no provision for making any use of erroneous frames like in EFR.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	215
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	216 TAF is a flag defined in GSM 06.31 section 6.1.1; if you don't have this flag,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	217 pass 0 - you will lose the function of comfort noise muting in the event of
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	218 prolonged SID loss, but all other Rx DTX functions will still work the same.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	219
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	220 With both functions the 33-byte buffer pointed to by frame_out is only an
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	221 output, i.e., prior buffer content is a don't-care. The frame generated by the
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	222 preprocessor may be substitution/muting, comfort noise or silence depending on
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	223 the state.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	224
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	225 gsmfr_preproc_bfi_bits() arguments bad_frame and frame_out can point to the
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	226 same memory: the function finishes analyzing bad_frame input before it starts
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	227 writing to frame_out.
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	228
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	229 GSM-FR full decoder
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	230 ===================
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	231
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	232 The full decoder is a high-level feature of libgsmfr2, incorporating both the
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	233 Rx DTX preprocessor block and the GSM 06.10 decoder block. The state structure
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	234 for the full decoder (struct gsmfr_fulldec_state) internally incorporates both
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	235 struct gsmfr_0610_state and gsmfr_preproc_state, but because it is implemented
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	236 inside libgsmfr2, it is still malloc'ed as a single chunk and can thus be
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	237 released with a single free() call. The functions for allocating and
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	238 initializing this state follow the established pattern:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	239
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	240 struct gsmfr_fulldec_state *gsmfr_fulldec_create(void);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	241
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	242 void gsmfr_fulldec_reset(struct gsmfr_fulldec_state *state);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	243
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	244 extern const unsigned gsmfr_fulldec_state_size;
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	245
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	246 The reset function internally calls gsmfr_0610_reset() and
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	247 gsmfr_preproc_reset(), initializing both processing blocks.
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	248
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	249 Frame processing functions are also straightforward:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	250
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	251 void gsmfr_fulldec_good_frame(struct gsmfr_fulldec_state *state,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	252 const uint8_t frame, int16_t pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	253
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	254 void gsmfr_fulldec_bfi(struct gsmfr_fulldec_state *state, int taf,
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	255 int16_t *pcm);
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	256
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	257 void gsmfr_fulldec_bfi_bits(struct gsmfr_fulldec_state *state,
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	258 const uint8_t bad_frame, int taf, int16_t pcm);
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	259
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	260 These functions follow the same pattern as gsmfr_preproc_good_frame(),
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	261 gsmfr_preproc_bfi() and gsmfr_preproc_bfi_bits(), but the output is a 160-sample
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	262 linear PCM buffer. Also note that the frame input to gsmfr_fulldec_good_frame()
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	263 is const, unlike the situation with gsmfr_preproc_good_frame() - the copying
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	264 into a scratchpad buffer (on the stack) happens inside this "fulldec" wrapper.
297 6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	265
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	266 The "fulldec" layer also adds the decoder homing feature:
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	267 gsmfr_fulldec_good_frame() detects decoder homing frames and invokes
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	268 gsmfr_fulldec_reset() when required, and also implements EHF output per the
6b479cfb06a4 beginning of libgsmfr2 documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	269 spec.
298 a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	270
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	271 Full decoder RTP input
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	272 ----------------------
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	273
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	274 If a network element is receiving GSM-FR input via RTP and needs to feed this
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	275 input to the decoder, the RTP payload handler needs to support both the basic
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	276 RTP format of ETSI TS 101 318 (also RFC 3551) and the extended RTP format of
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	277 TW-TS-001. Depending on the format received, and depending on bit flags in the
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	278 TEH octet in the case of TW-TS-001, one of the 3 main processing functions
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	279 listed above will need to be called. Seeing that this complex logic should be
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	280 abstracted away from applications into the library, we've added the following
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	281 wrapper function:
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	282
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	283 int gsmfr_fulldec_rtp_in(struct gsmfr_fulldec_state *state,
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	284 const uint8_t *rtp_pl, unsigned rtp_pl_len,
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	285 int16_t *pcm);
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	286
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	287 The input is the received RTP payload: array of bytes and length. It is
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	288 acceptable to pass 0 as rtp_pl_len, in which case rtp_pl pointer can be NULL.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	289 The function proceeds as follows:
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	290
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	291 * If the input is valid RTP format for GSM-FR (either basic or extended), it is
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	292 passed to the appropriate main processing function. Unlike the permissive
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	293 stance taken in lower-level functions, RTP input validation includes a check
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	294 of 0xD signature of GSM-FR, as well as validation of TEH octet signature and
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	295 consistency in the case of TW-TS-001. The return value is 0, indicating that
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	296 good input was received.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	297
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	298 * If the input is a zero-length payload (rtp_pl_len is 0, rtp_pl may be NULL),
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	299 it is treated like BFI-no-data with TAF=0. The return value is 0, meaning
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	300 that this input is still considered valid.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	301
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	302 * All other inputs are considered invalid. Linear PCM output is still generated
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	303 by calling gsmfr_fulldec_bfi(), but the return value is -1, signaling invalid
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	304 RTP input.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	305
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	306 TFO transform
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	307 =============
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	308
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	309 "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	310 transform on GSM codec frames called for by the TFO spec, 3GPP TS 28.062
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	311 section C.3.2.1.1. For each of the 3 classic GSM codecs, this transform can
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	312 operate in two modes:
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	313
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	314 DTXd=0: the input UL frame stream from call leg A may contain SIDs and BFI
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	315 frame gaps, but the output to call leg B DL must be 100% valid frames and
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	316 SID-free.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	317
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	318 DTXd=1: the output to call leg B DL is allowed to contain both good speech and
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	319 valid SID frames, just like the output of a DTX-enabled speech encoder.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	320 Furthermore, it can be presumed that network operators who enable DTXd seek to
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	321 reap its benefits in terms of radio interference reduction, hence the
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	322 DTXd-enabled TFO transform should actually make use of DTXd capability.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	323
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	324 In the case of GSM-FR codec, the TFO transform with DTXd=0 is identical to the
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	325 Rx DTX preprocessor part of the standard endpoint decoder, hence our "preproc"
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	326 block is directly suited to serve as such. OTOH, the case of DTXd=1 is
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	327 different: heeding the implied need to actually make use of DTXd when possible
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	328 requires implementing a transform that is not the same as the preprocessor to
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	329 be applied just prior to local GSM 06.10 decoding, hence the DTXd-enabled TFO
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	330 transform is a different entity.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	331
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	332 The approach implemented in Themyscira libgsmfr2 is a hybrid:
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	333
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	334 * The preprocessor block described earlier in this document functions both as
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	335 the necessary component of the full endpoint decoder and as the TFO transform
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	336 for DTXd=0.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	337
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	338 * TFO transform for DTXd=1 is implemented as a two-step process:
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	339
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	340 1) Regular main processing functions of the preproc block produce output that
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	341 is SID-free, containing synthetic "speech" frames in the case of comfort
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	342 noise or silence.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	343
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	344 2) A special post-processor function needs to be called immediately afterward.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	345 This function selectively transforms some output frames into SIDs based on
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	346 a flag set in the state structure.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	347
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	348 In order to make this approach possible, all main processing functions of the
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	349 preproc block do a little bit of extra housekeeping to keep track of whether or
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	350 not their output can be replaced with SID, logic that is unnecessary when this
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	351 block functions as part of the full endpoint decoder or as non-DTXd TFO
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	352 transform. However, this logic is very simple and the overhead is very light.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	353
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	354 TFO transform API
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	355 -----------------
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	356
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	357 The state structure was already described earlier: it is
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	358 struct gsmfr_preproc_state, created either with gsmfr_preproc_create() or by
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	359 externally allocating the needed memory based on gsmfr_preproc_state_size and
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	360 then initializing it with gsmfr_preproc_reset(). The following API functions
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	361 are then available:
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	362
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	363 int gsmfr_tfo_xfrm_main(struct gsmfr_preproc_state *state,
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	364 const uint8_t *rtp_in, unsigned rtp_in_len,
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	365 uint8_t *frame_out);
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	366
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	367 int gsmfr_tfo_xfrm_dtxd(struct gsmfr_preproc_state state, uint8_t frame_out);
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	368
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	369 gsmfr_tfo_xfrm_main() is the TFO transform counterpart to
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	370 gsmfr_fulldec_rtp_in(), described in detail earlier. It is also possible (and
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	371 allowed) to call gsmfr_preproc_* main processing functions directly, but the
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	372 RTP wrapper is convenient for the same reasons as in the case of the full
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	373 decoder. In this mode of usage, the only difference between the full decoder
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	374 and the TFO transform is that the former emits linear PCM output, whereas the
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	375 latter emits 33-byte GSM-FR codec frames to be sent to call leg B downlink.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	376
536 a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_* Mychaela Falconia <falcon@freecalypso.org> parents: 535 diff changeset	377 The return value from gsmfr_tfo_xfrm_main() is the same as that of
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_* Mychaela Falconia <falcon@freecalypso.org> parents: 535 diff changeset	378 gsmfr_fulldec_rtp_in(): 0 if the the RTP input was considered good or -1 if it
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_* Mychaela Falconia <falcon@freecalypso.org> parents: 535 diff changeset	379 is invalid. In the case of invalid RTP input that produces -1 return value,
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_* Mychaela Falconia <falcon@freecalypso.org> parents: 535 diff changeset	380 gsmfr_tfo_xfrm_main() calls gsmfr_preproc_bfi(), just like how
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_* Mychaela Falconia <falcon@freecalypso.org> parents: 535 diff changeset	381 gsmfr_fulldec_rtp_in() calls gsmfr_fulldec_bfi() under the same conditions.
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_* Mychaela Falconia <falcon@freecalypso.org> parents: 535 diff changeset	382
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	383 If DTXd is in use, then the call to gsmfr_tfo_xfrm_main() needs to be directly
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	384 followed by a call to gsmfr_tfo_xfrm_dtxd(), operating on the same output buffer
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	385 with the same state structure. The output will then be changed to SID when
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	386 appropriate for the current state.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	387
536 a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_* Mychaela Falconia <falcon@freecalypso.org> parents: 535 diff changeset	388 The return value from gsmfr_tfo_xfrm_dtxd() is the SP flag of GSM 06.31: 1 if
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_* Mychaela Falconia <falcon@freecalypso.org> parents: 535 diff changeset	389 the output frame is speech or 0 if it is SID.
a3300483ae74 doc/FR1-library-API: document return value from gsmfr_tfo_xfrm_* Mychaela Falconia <falcon@freecalypso.org> parents: 535 diff changeset	390
535 bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	391 TFO transform homing
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	392 --------------------
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	393
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	394 3GPP specs are silent on whether or not TFO transforms should implement homing,
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	395 i.e., whether or not they should reset to home state when a decoder homing frame
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	396 passes through. However, at Themyscira Wireless we believe in building
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	397 deterministic systems whose bit-exact behavior can be modeled and relied upon;
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	398 for this reason, our implementation of TFO transform does include in-band
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	399 homing. In accord with this design decision, gsmfr_tfo_xfrm_main() internally
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	400 calls gsmfr_preproc_good_frame_hm() described earlier instead of plain
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	401 gsmfr_preproc_good_frame().
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	402
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	403 With DTXd=1, if a stream of DHFs is input to the TFO transform, the same stream
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	404 of DHFs will appear on the output, i.e., DTXd won't kick in. (The same behavior
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	405 occurs in a standard 3GPP-compliant speech encoder whose input is a stream of
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	406 0xD5 octets in PCMA or 0xFE in PCMU.) However, any BFIs following this DHF
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	407 will be immediately converted to SID, under the same conditions when our TFO
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	408 transform with DTXd=0 emits silence frames of GSM 06.11.
bf7bbc7d494f doc/FR1-library-API: document new additions Mychaela Falconia <falcon@freecalypso.org> parents: 299 diff changeset	409
298 a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	410 Stateless utility functions
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	411 ===========================
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	412
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	413 Conversions between RTP packed format and broken-down codec parameters are
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	414 stateless and implemented with highly efficient code. There are two versions;
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	415 this version converts between packed frames and struct gsmfr_param_frame used
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	416 by 06.10 encoder and decoder functions:
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	417
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	418 void gsmfr_pack_frame(const struct gsmfr_param_frame param, uint8_t frame);
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	419 void gsmfr_unpack_frame(const uint8_t frame, struct gsmfr_param_frame param);
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	420
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	421 and this version converts between packed frames and a straight linear array of
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	422 76 parameters:
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	423
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	424 void gsmfr_pack_from_array(const int16_t params, uint8_t frame);
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	425 void gsmfr_unpack_to_array(const uint8_t frame, int16_t params);
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	426
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	427 The latter functions gsmfr_pack_from_array() and gsmfr_unpack_to_array() are
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	428 drop-in replacements for gsm_implode() and gsm_explode() from old libgsm. The
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	429 order of parameters in this array is the canonical one: first all LARc, then
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	430 all params for the first subframe, then the second subframe, then the third and
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	431 the fourth. OTOH, struct gsmfr_param_frame uses functional grouping, chosen
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	432 for ease of porting of original libgsm code.
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	433
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	434 Both unpacking functions (gsmfr_unpack_frame() and gsmfr_unpack_to_array())
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	435 ignore the upper nibble of the first byte, i.e., the 0xD signature is not
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	436 enforced. However, this signature is always set correctly by gsmfr_pack_frame()
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	437 and gsmfr_pack_from_array(), and also by gsmfr_0610_encode_frame() function
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	438 which calls gsmfr_pack_frame() as its finishing step.
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	439
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	440 The last remaining stateless utility function performs SID classification of
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	441 received GSM-FR frames:
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	442
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	443 int gsmfr_preproc_sid_classify(const uint8_t *frame);
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	444
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	445 This function analyzes an RTP-encoded FR frame (the upper nibble of the first
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	446 byte is NOT checked for 0xD signature) for the SID codeword of GSM 06.12 and
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	447 classifies the frame as SID=0, SID=1 or SID=2 per the rules of GSM 06.31
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	448 section 6.1.1. This classification is the first processing step performed by
a45f806cada9 doc/FR1-library-API: document stateless utility functions Mychaela Falconia <falcon@freecalypso.org> parents: 297 diff changeset	449 gsmfr_preproc_good_frame().
299 59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	450
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	451 Public constant definitions
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	452 ===========================
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	453
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	454 Our public header file <tw_gsmfr.h> provides these constant definitions, which
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	455 should be self-explanatory:
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	456
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	457 #define GSMFR_RTP_FRAME_LEN 33
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	458 #define GSMFR_NUM_PARAMS 76
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	459
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	460 Public const data items
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	461 =======================
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	462
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	463 There are two special GSM-FR frame bit patterns defined in the specs: there is
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	464 the silence frame of GSM 06.11, and there is the decoder homing frame specified
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	465 in later versions of GSM 06.10. RTP-packed representations of both frames are
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	466 included in libgsmfr2, and are made public:
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	467
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	468 extern const uint8_t gsmfr_preproc_silence_frame[GSMFR_RTP_FRAME_LEN];
59751c8fc773 doc/FR1-library-API: finish in first pass Mychaela Falconia <falcon@freecalypso.org> parents: 298 diff changeset	469 extern const uint8_t gsmfr_decoder_homing_frame[GSMFR_RTP_FRAME_LEN];

FreeCalypso > hg > gsm-codec-lib

annotate doc/FR1-library-API @ 585:3c6bf0d26ee7 default tip