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

annotate doc/EFR-library-API @ 282:9ee8ad3d4d30

frtest: rm gsmfr-hand-test and gsmfr-max-out utils These hack programs were never properly documented and were written only as part of a debug chase, in pursuit of a bug that ultimately turned out to be in our then-hacky patch to osmo-bts-sysmo, before beginning of proper patches in Osmocom. These hack programs need to be dropped from the present sw package because they depend on old libgsm, and we are eliminating that dependency.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Sun, 14 Apr 2024 05:44:47 +0000
parents	fe5aceaf51e0
children	9208db14b4b9

rev	line source
123 92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 The external public interface to Themyscira libgsmefr consists of a single
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 header file <gsm_efr.h>; it should be installed in the same system include
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	3 directory as <gsm.h> from classic libgsm (1990s free software product) for the
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	4 original FR codec, and the API of libgsmefr is modeled after that of libgsm.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	5
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	6 The dialect of C we chose for libgsmefr is ANSI C (function prototypes), const
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	7 qualifier is used where appropriate, and the interface is defined in terms of
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	8 <stdint.h> types; <gsm_efr.h> includes <stdint.h>.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	9
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	10 State allocation and freeing
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	11 ============================
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	12
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	13 In order to use the EFR encoder, you will need to allocate an encoder state
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	14 structure, and to use the EFR decoder, you will need to allocate a decoder state
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	15 structure. The necessary state allocation functions are:
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	16
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	17 extern struct EFR_encoder_state *EFR_encoder_create(int dtx);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	18 extern struct EFR_decoder_state *EFR_decoder_create(void);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	19
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	20 struct EFR_encoder_state and struct EFR_decoder_state are opaque structures to
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	21 library users: you only get pointers which you remember and pass around, but
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	22 <gsm_efr.h> does not give you full definitions of these structs. As a library
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	23 user, you don't even get to know the size of these structs, hence the necessary
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	24 malloc() operation happens inside EFR_encoder_create() and EFR_decoder_create().
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	25 However, each structure is malloc'ed as a single chunk, hence when you are done
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	26 with it, simply call free() to relinquish each encoder or decoder state
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	27 instance.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	29 EFR_encoder_create() and EFR_decoder_create() functions can fail if the malloc()
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	30 call inside fails, in which case the two libgsmefr functions in question return
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31 NULL.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	32
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	33 The dtx argument to EFR_encoder_create() is a Boolean flag represented as an
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	34 int; it tells the EFR encoder whether it should operate with DTX enabled (run
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	35 GSM 06.82 VAD and emit SID frames instead of speech frames per GSM 06.81) or DTX
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	36 disabled (skip VAD and always emit speech frames).
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	37
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	38 Using the EFR encoder
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	39 =====================
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	40
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	41 To encode one 20 ms audio frame per EFR, call EFR_encode_frame():
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	42
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	43 extern void EFR_encode_frame(struct EFR_encoder_state st, const int16_t pcm,
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	44 uint8_t frame, int sp, int *vad);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	45
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	46 You need to provide an encoder state structure allocated earlier with
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	47 EFR_encoder_create(), a block of 160 linear PCM samples, and an output buffer of
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	48 31 bytes (EFR_RTP_FRAME_LEN constant also defined in <gsm_efr.h>) into which the
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	49 encoded EFR frame will be written; the frame format is that defined in ETSI TS
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	50 101 318 for EFR in RTP, including the 0xC signature in the upper nibble of the
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	51 first byte.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	52
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	53 The last two arguments of type (int *) are optional pointers to extra output
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	54 flags SP and VAD, defined in GSM 06.81 section 5.1.1; either pointer or both of
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	55 them can be NULL if these extra output flags aren't needed. Both of these flags
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	56 are needed in order to test our libgsmefr encoder implementation against
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	57 official ETSI test sequences (GSM 06.54), but they typically aren't needed
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	58 otherwise.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	59
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	60 Using the EFR decoder
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	61 =====================
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	62
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	63 The main interface to our EFR decoder is this function:
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	64
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	65 extern void EFR_decode_frame(struct EFR_decoder_state st, const uint8_t frame,
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	66 int bfi, int taf, int16_t *pcm);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	67
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	68 The inputs consist of 244 bits of frame payload (the 4 upper bits of the first
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	69 byte are ignored - there is NO enforcement of 0xC signature in our frame
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	70 decoder) and BFI and TAF flags defined in GSM 06.81 section 6.1.1. Note the
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	71 absence of a SID flag argument: EFR_decode_frame() calls our own utility
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	72 function EFR_sid_classify() to determine SID from the frame itself per the rules
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	73 of GSM 06.81 section 6.1.1.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	74
161 fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	75 The canonical EFR decoder always expects frame bits input to be present, even
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	76 during BFI condtions! More specifically, if a BFI=1 decoding call comes in when
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	77 the decoder is in comfort noise generation state (after a SID), then all frame
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	78 bits passed along with BFI=1 are ignored as one would naturally expect for
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	79 frames that typically aren't transmitted at all - but if a BFI=1 decoding call
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	80 comes in when the decoder is in regular speech mode, the canonical decoder will
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	81 use the "fixed codebook excitation pulses" part of the erroneous frame (one
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	82 declared to be garbage) as part of its decoding operation! (This part
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	83 constitutes 35 bits per subframe or 140 bits out of 244 per frame.)
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	84
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	85 BFI with no data
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	86 ================
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	87
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	88 Many EFR decoder applications will be faced with a situation where they receive
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	89 a frame gap (no data at all), and they need to run the EFR decoder with BFI=1 -
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	90 but the application doesn't have any frame-bits input. Yet the canonical EFR
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	91 decoder requires some erroneous frame bits to be fed to it - so what gives?
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	92 Our initial approach was to feed the decoder all zeros in the place of codec
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	93 parameters - but further analysis reveals that approach to be bad. (To see for
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	94 yourself, study the code in d1035pf.c and think what it will do when the input
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	95 is fixed at all zeros.) Our new approach is to generate pseudorandom bits for
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	96 these pulse parameters, as detailed below.
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	97
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	98 If you find yourself in the situation of needing to feed BFI=1 with no frame
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	99 data bits to the decoder, call the following function in the place of
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	100 EFR_decode_frame():
123 92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	101
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	102 extern void EFR_decode_bfi_nodata(struct EFR_decoder_state *st, int taf,
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	103 int16_t *pcm);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	104
161 fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	105 This function begins by checking the internal state flag RX_SP_FLAG, indicating
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	106 whether the decoder is in speech or comfort noise generation mode. If
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	107 RX_SP_FLAG is set, indicating speech state, then the main body of the decoder
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	108 will be making use of fixed codebook pulse parameters even for erroneous frames,
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	109 and EFR_decode_bfi_nodata() will invoke a PRNG to fill in pseudorandom bits.
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	110 If RX_SP_FLAG is clear, then the decoder is generating comfort noise following
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	111 reception of a SID, and BFI conditions are fully expected because the
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	112 transmitter is expected to be off. In this case EFR_decode_bfi_nodata() feeds
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	113 all-zeros parameters to the main body of the decoder, as none of them will be
fe5aceaf51e0 doc/EFR-library-API: document new handling of BFI with no data Mychaela Falconia <falcon@freecalypso.org> parents: 130 diff changeset	114 used.
123 92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	115
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	116 Stateless utility functions
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	117 ===========================
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	118
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	119 All functions in this section are stateless (no encoder state or decoder state
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	120 structure is needed); they merely manipulate bit fields.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	121
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	122 extern void EFR_frame2params(const uint8_t frame, int16_t params);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	123
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	124 This function unpacks an EFR codec frame in ETSI TS 101 318 RTP encoding (the
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	125 upper nibble of the first byte is NOT checked, i.e., there is NO enforcement of
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	126 0xC signature) into an array of 57 (EFR_NUM_PARAMS) parameter words for the
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	127 codec. int16_t signed type is used for the params array (even though all
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	128 parameters are actually unsigned) in order to match the guts of ETSI-based EFR
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	129 codec, and EFR_frame2params() is called internally by EFR_decode_frame().
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	130
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	131 extern void EFR_params2frame(const int16_t params, uint8_t frame);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	132
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	133 This function takes an array of 57 (EFR_NUM_PARAMS) EFR codec parameter words
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	134 and packs them into a 31-byte (EFR_RTP_FRAME_LEN) frame in ETSI TS 101 318
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	135 format. The 0xC signature is generated by this function, and every byte of the
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	136 output buffer is fully written without regard to any previous content. This
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	137 function is called internally by EFR_encode_frame().
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	138
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	139 extern int EFR_sid_classify(const uint8_t *frame);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	140
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	141 This function analyzes an RTP-encoded EFR frame (the upper nibble of the first
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	142 byte is NOT checked for 0xC signature) for the SID codeword of GSM 06.62 and
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	143 classifies the frame as SID=0, SID=1 or SID=2 per the rules of GSM 06.81
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	144 section 6.1.1.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	145
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	146 extern void EFR_insert_sid_codeword(uint8_t *frame);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	147
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	148 This function inserts the SID codeword of GSM 06.62 into the frame in the
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	149 pointed-to buffer; specifically, the 95 bits that make up the SID field are all
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	150 set to 1s, but all other bits remain unchanged. This function is arguably least
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	151 useful to external users of libgsmefr, but it exists because of how the original
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	152 code from ETSI generates SID frames produced by the encoder in DTX mode.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	153
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	154 Parameter-based encoder and decoder functions
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	155 =============================================
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	156
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	157 The EFR_encode_frame() and EFR_decode_frame() functions described earlier in
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	158 this document constitute the most practically useful (intended for actual use)
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	159 interfaces to our EFR encoder and decoder, but they are actually wrappers around
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	160 these parameter-based functions:
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	161
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	162 extern void EFR_encode_params(struct EFR_encoder_state st, const int16_t pcm,
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	163 int16_t params, int sp, int *vad);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	164
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	165 This function is similar to EFR_encode_frame(), but the output is an array of
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	166 57 (EFR_NUM_PARAMS) codec parameter words rather than a finished frame. The two
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	167 extra output flags are optional (pointers may be NULL) just like with
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	168 EFR_encode_frame(), but there is a catch: if the output frame is a SID (which
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	169 can only happen if DTX is enabled), the bits inside parameter words that would
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	170 correspond to SID codeword bits are NOT set, instead one MUST call
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	171 EFR_insert_sid_codeword() after packing the frame with EFR_params2frame(). The
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	172 wrapper in EFR_encode_frame() does exactly as described, and the overall logic
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	173 follows the original code structure from ETSI.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	174
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	175 extern void EFR_decode_params(struct EFR_decoder_state *st,
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	176 const int16_t *params, int bfi, int sid, int taf,
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	177 int16_t *pcm);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	178
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	179 This function is similar to EFR_decode_frame() with the frame input replaced
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	180 with params array input, but the SID classification per the rules of GSM 06.81
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	181 section 6.1.1 needs to be provided by the caller. The wrapper in
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	182 EFR_decode_frame() calls both EFR_frame2params() and EFR_sid_classify() before
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	183 passing the work to EFR_decode_params().
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	184
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	185 State reset functions
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	186 =====================
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	187
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	188 extern void EFR_encoder_reset(struct EFR_encoder_state *st, int dtx);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	189 extern void EFR_decoder_reset(struct EFR_decoder_state *st);
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	190
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	191 These functions reset the state of the encoder or the decoder, respectively;
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	192 the entire state structure is fully initialized to the respective home state
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	193 defined in GSM 06.60 section 8.5 for the encoder or section 8.6 for the decoder.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	194
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	195 EFR_encoder_reset() is called internally by EFR_encoder_create() and by the
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	196 encoder itself when it encounters the ETSI-prescribed encoder homing frame;
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	197 EFR_decoder_reset() is called internally by EFR_decoder_create() and by the
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	198 decoder itself when it encounters the ETSI-prescribed decoder homing frame.
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	199 Therefore, there is generally no need for libgsmefr users to call these
92fdb499b5c3 doc/EFR-library-API article written Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	200 functions directly - but they are made public for the sake of completeness.
130 1c529bb31219 doc/EFR-library-API: explain dtx argument to EFR_encoder_reset() Mychaela Falconia <falcon@freecalypso.org> parents: 123 diff changeset	201
1c529bb31219 doc/EFR-library-API: explain dtx argument to EFR_encoder_reset() Mychaela Falconia <falcon@freecalypso.org> parents: 123 diff changeset	202 If you call EFR_encoder_reset() manually, you can change the DTX enable/disable
1c529bb31219 doc/EFR-library-API: explain dtx argument to EFR_encoder_reset() Mychaela Falconia <falcon@freecalypso.org> parents: 123 diff changeset	203 flag from its initial value given to EFR_encoder_create() - the new value of
1c529bb31219 doc/EFR-library-API: explain dtx argument to EFR_encoder_reset() Mychaela Falconia <falcon@freecalypso.org> parents: 123 diff changeset	204 this flag passed to EFR_encoder_reset() always takes effect. There is no
1c529bb31219 doc/EFR-library-API: explain dtx argument to EFR_encoder_reset() Mychaela Falconia <falcon@freecalypso.org> parents: 123 diff changeset	205 provision for changing this mode within an encoder session without a full reset.

FreeCalypso > hg > gsm-codec-lib

annotate doc/EFR-library-API @ 282:9ee8ad3d4d30