FreeCalypso > hg > gsm-codec-lib

annotate doc/EFR-library-API @ 134:170e03b20337

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/EFR-testing (gsmefr-{cod,dec}-parse): document similarity to gsmrec-dump
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 11 Dec 2022 05:26:08 +0000
parents 1c529bb31219
children fe5aceaf51e0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 Many EFR decoder applications will also be faced with a situation where they
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 receive a frame gap (no data at all), and they need to run the EFR decoder with
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 BFI=1, but don't have any frame-bits input. If you find yourself in this
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 situation, call the following function:
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 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
81 int16_t *pcm);
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 EFR_decode_bfi_nodata() is equivalent to calling EFR_decode_frame() with a frame
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 buffer of 31 zero bytes (or 0xC signature followed by 244 zero bits) and BFI=1,
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 but is slightly more efficient in that the internal steps of EFR_frame2params()
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 and EFR_sid_classify() are skipped, and the made-up "frame" of 244 zero bits is
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 passed to the decoder core at the params array level.
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 Note that the official EFR decoder from ETSI, which we've replicated in our
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 librified form in libgsmefr, does make use of some presumed-invalid frame data
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 bits under BFI=1 conditions: see the description in GSM 06.61 section 6.1, where
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 the last sentence reads "The received fixed codebook excitation pulses from the
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 erroneous frame are always used as such." With our current implementation, the
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 "erroneous frame" in the case of completely lost or missing frames is a made-up
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 frame of 244 zero bits; the question of whether this approach is good enough or
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 if we need to do something more complex remains for further study.
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 Stateless utility functions
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 ===========================
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 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
102 structure is needed); they merely manipulate bit fields.
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_frame2params(const uint8_t *frame, int16_t *params);
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 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
107 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
108 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
109 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
110 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
111 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
112
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 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
114
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 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
116 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
117 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
118 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
119 function is called internally by EFR_encode_frame().
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 extern int EFR_sid_classify(const uint8_t *frame);
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 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
124 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
125 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
126 section 6.1.1.
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 extern void EFR_insert_sid_codeword(uint8_t *frame);
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 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
131 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
132 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
133 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
134 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
135
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136 Parameter-based encoder and decoder functions
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137 =============================================
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 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
140 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
141 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
142 these parameter-based functions:
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 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
145 int16_t *params, int *sp, int *vad);
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147 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
148 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
149 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
150 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
151 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
152 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
153 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
154 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
155 follows the original code structure from ETSI.
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 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
158 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
159 int16_t *pcm);
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 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
162 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
163 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
164 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
165 passing the work to EFR_decode_params().
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 State reset functions
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 =====================
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170 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
171 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
172
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 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
174 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
175 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
176
92fdb499b5c3 doc/EFR-library-API article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177 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
178 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
179 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
180 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
181 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
182 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
183
1c529bb31219 doc/EFR-library-API: explain dtx argument to EFR_encoder_reset()
Mychaela Falconia <falcon@freecalypso.org>
parents: 123
diff changeset
184 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
185 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
186 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
187 provision for changing this mode within an encoder session without a full reset.