FreeCalypso > hg > gsm-codec-lib
annotate doc/EFR-library-API @ 489:f036e1de5b05
libgsmhr1: starting with API definition
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sat, 15 Jun 2024 04:51:30 +0000 |
parents | 2d46abdfbe91 |
children |
rev | line source |
---|---|
463
9208db14b4b9
doc/EFR-library-API: rm reference to old libgsm
Mychaela Falconia <falcon@freecalypso.org>
parents:
161
diff
changeset
|
1 Libgsmefr general usage |
9208db14b4b9
doc/EFR-library-API: rm reference to old libgsm
Mychaela Falconia <falcon@freecalypso.org>
parents:
161
diff
changeset
|
2 ======================= |
9208db14b4b9
doc/EFR-library-API: rm reference to old libgsm
Mychaela Falconia <falcon@freecalypso.org>
parents:
161
diff
changeset
|
3 |
123
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
4 The external public interface to Themyscira libgsmefr consists of a single |
463
9208db14b4b9
doc/EFR-library-API: rm reference to old libgsm
Mychaela Falconia <falcon@freecalypso.org>
parents:
161
diff
changeset
|
5 header file <gsm_efr.h>; it should be installed in some system include |
9208db14b4b9
doc/EFR-library-API: rm reference to old libgsm
Mychaela Falconia <falcon@freecalypso.org>
parents:
161
diff
changeset
|
6 directory. |
123
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
7 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
8 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
|
9 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
|
10 <stdint.h> types; <gsm_efr.h> includes <stdint.h>. |
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 State allocation and freeing |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
13 ============================ |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
14 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
15 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
|
16 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
|
17 structure. The necessary state allocation functions are: |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
18 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
19 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
|
20 extern struct EFR_decoder_state *EFR_decoder_create(void); |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
21 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
22 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
|
23 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
|
24 <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
|
25 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
|
26 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
|
27 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
|
28 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
|
29 instance. |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
30 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
31 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
|
32 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
|
33 NULL. |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
34 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
35 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
|
36 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
|
37 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
|
38 disabled (skip VAD and always emit speech frames). |
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 Using the EFR encoder |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
41 ===================== |
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 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
|
44 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
45 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
|
46 uint8_t *frame, int *sp, int *vad); |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
47 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
48 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
|
49 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
|
50 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
|
51 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
|
52 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
|
53 first byte. |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
54 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
55 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
|
56 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
|
57 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
|
58 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
|
59 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
|
60 otherwise. |
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 Using the EFR decoder |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
63 ===================== |
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 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
|
66 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
67 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
|
68 int bfi, int taf, int16_t *pcm); |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
69 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
70 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
|
71 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
|
72 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
|
73 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
|
74 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
|
75 of GSM 06.81 section 6.1.1. |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
76 |
161
fe5aceaf51e0
doc/EFR-library-API: document new handling of BFI with no data
Mychaela Falconia <falcon@freecalypso.org>
parents:
130
diff
changeset
|
77 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
|
78 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
|
79 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
|
80 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
|
81 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
|
82 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
|
83 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
|
84 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
|
85 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
|
86 |
fe5aceaf51e0
doc/EFR-library-API: document new handling of BFI with no data
Mychaela Falconia <falcon@freecalypso.org>
parents:
130
diff
changeset
|
87 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
|
88 ================ |
fe5aceaf51e0
doc/EFR-library-API: document new handling of BFI with no data
Mychaela Falconia <falcon@freecalypso.org>
parents:
130
diff
changeset
|
89 |
fe5aceaf51e0
doc/EFR-library-API: document new handling of BFI with no data
Mychaela Falconia <falcon@freecalypso.org>
parents:
130
diff
changeset
|
90 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
|
91 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
|
92 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
|
93 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
|
94 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
|
95 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
|
96 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
|
97 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
|
98 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
|
99 |
fe5aceaf51e0
doc/EFR-library-API: document new handling of BFI with no data
Mychaela Falconia <falcon@freecalypso.org>
parents:
130
diff
changeset
|
100 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
|
101 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
|
102 EFR_decode_frame(): |
123
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
103 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
104 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
|
105 int16_t *pcm); |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
106 |
161
fe5aceaf51e0
doc/EFR-library-API: document new handling of BFI with no data
Mychaela Falconia <falcon@freecalypso.org>
parents:
130
diff
changeset
|
107 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
|
108 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
|
109 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
|
110 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
|
111 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
|
112 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
|
113 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
|
114 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
|
115 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
|
116 used. |
123
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 Stateless utility functions |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
119 =========================== |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
120 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
121 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
|
122 structure is needed); they merely manipulate bit fields. |
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 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
|
125 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
126 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
|
127 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
|
128 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
|
129 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
|
130 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
|
131 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
|
132 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
133 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
|
134 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
135 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
|
136 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
|
137 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
|
138 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
|
139 function is called internally by EFR_encode_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 extern int EFR_sid_classify(const uint8_t *frame); |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
142 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
143 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
|
144 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
|
145 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
|
146 section 6.1.1. |
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 extern void EFR_insert_sid_codeword(uint8_t *frame); |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
149 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
150 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
|
151 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
|
152 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
|
153 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
|
154 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
|
155 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
156 Parameter-based encoder and decoder functions |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
157 ============================================= |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
158 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
159 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
|
160 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
|
161 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
|
162 these parameter-based functions: |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
163 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
164 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
|
165 int16_t *params, int *sp, int *vad); |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
166 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
167 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
|
168 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
|
169 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
|
170 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
|
171 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
|
172 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
|
173 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
|
174 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
|
175 follows the original code structure from ETSI. |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
176 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
177 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
|
178 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
|
179 int16_t *pcm); |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
180 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
181 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
|
182 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
|
183 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
|
184 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
|
185 passing the work to EFR_decode_params(). |
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 State reset functions |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
188 ===================== |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
189 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
190 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
|
191 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
|
192 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
193 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
|
194 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
|
195 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
|
196 |
92fdb499b5c3
doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
197 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
|
198 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
|
199 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
|
200 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
|
201 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
|
202 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
|
203 |
1c529bb31219
doc/EFR-library-API: explain dtx argument to EFR_encoder_reset()
Mychaela Falconia <falcon@freecalypso.org>
parents:
123
diff
changeset
|
204 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
|
205 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
|
206 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
|
207 provision for changing this mode within an encoder session without a full reset. |
473
2d46abdfbe91
libgsmefr version 1.1.0 for DHF addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
463
diff
changeset
|
208 |
2d46abdfbe91
libgsmefr version 1.1.0 for DHF addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
463
diff
changeset
|
209 Public const datum: decoder homing frame |
2d46abdfbe91
libgsmefr version 1.1.0 for DHF addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
463
diff
changeset
|
210 ======================================== |
2d46abdfbe91
libgsmefr version 1.1.0 for DHF addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
463
diff
changeset
|
211 |
2d46abdfbe91
libgsmefr version 1.1.0 for DHF addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
463
diff
changeset
|
212 While the encoder homing frame is the same for all codecs defined by ETSI and |
2d46abdfbe91
libgsmefr version 1.1.0 for DHF addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
463
diff
changeset
|
213 then later 3GPP, each codec has its own unique decoder homing frame (DHF). A |
2d46abdfbe91
libgsmefr version 1.1.0 for DHF addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
463
diff
changeset
|
214 public const datum introduced in libgsmefr version 1.1.0 provides the |
2d46abdfbe91
libgsmefr version 1.1.0 for DHF addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
463
diff
changeset
|
215 RTP-encoded form of the ETSI-prescribed DHF for EFR: |
2d46abdfbe91
libgsmefr version 1.1.0 for DHF addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
463
diff
changeset
|
216 |
2d46abdfbe91
libgsmefr version 1.1.0 for DHF addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
463
diff
changeset
|
217 extern const uint8_t EFR_decoder_homing_frame[EFR_RTP_FRAME_LEN]; |