FreeCalypso > hg > gsm-codec-lib

annotate doc/HR-codec-library @ 635:723265aea9f8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/HR-codec-library: finish library documentation
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 20 Mar 2026 04:27:04 +0000
parents 3ab76caba41c
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
632
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Themyscira libgsmhr1: library for GSM-HR codec
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 ==============================================
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 The present library provides the following functionalities related to GSM-HR
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 speech codec, also known as HRv1:
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 * Stateful speech encoder and decoder engines based on GSM 06.06 reference code
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 from ETSI;
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 * TS 28.062 section C.3.2.1.1 stateful TFO transform for this codec;
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 * A rich set of stateless utility functions for format conversion and other
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 common manipulations.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 Compared to libgsmhr alternative implemented as part of Osmocom gapk, our
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 implementation provides the following advantages:
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 * In our librification of ETSI GSM-HR code, speech encoder and decoder engines
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 have been outfitted with proper state structures, as opposed to the hack of
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 treating the entire bss segment with global variables as a poor man's state
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 structure.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 * The Rx front end has been factored out of the speech decoder and can also be
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 used as a TFO transform. Because HRv1 codec falls chronologically between
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 FRv1 and EFR, our TFO transform for HRv1 serves as a stepping stone toward
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 future work on TFO transform for EFR.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 * We made a slight extension to this GSM-HR Rx front end, applicable to both
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 full decoder and TFO transform configurations, to support BFI without payload
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 bits. This condition occurs in the case of FACCH stealing, packet loss in IP
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 transport, or the non-modifiable DSP PHY implementation in sysmoBTS that does
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 not provide erroneous payload bits along with BFI.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 * We added many format conversion and other utility functions that are
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 Themyscira original work, not from ETSI GSM-HR code.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 However, because of very limited practical utility of GSM-HR codec, almost no
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 work has been done to speed up any of the grossly inefficient code that
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 originates from ETSI - see HR-codec-limits article.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 GSM-HR codec frame formats
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 ==========================
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 Our speech encoder, speech decoder and TFO transform engines operate on the
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 same canonical formats as the original reference code from ETSI:
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 * The output from our speech encoder engine for each frame is an array of 20
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 16-bit words (18 codec parameters followed by VAD and SP flags) that matches
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 ETSI *.cod format.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 * The input format to our speech decoder engine is an array of 22 16-bit words
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 (18 codec parameters followed by BFI, UFI, SID and TAF) as represented in
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 ETSI *.dec format.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 * The input format to our TFO transform implementation is a decoder input frame
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 (*.dec), and the output mimics an encoder output (*.cod) frame complete with
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 VAD and SP flags. (The latter outputs are VAD=1 SP=1 in the case of DTXd=0,
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 or VAD=0 dummy and correct SP output in the case of DTXd=1.)
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 All other standard formats for GSM-HR codec frames, namely TS 101 318, RFC 5993
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 and TW-TS-002, are supported via stateless format conversion functions.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 Representation and handling of BFI
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 ----------------------------------
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 If a decoder input frame in the canonical 22-word *.dec format has BFI=1 and
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 SID=0, it is a non-SID BFI frame, also called an unusable frame in GSM 06.41
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 spec. If such frame arrives in comfort noise insertion state, all parameters
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 are ignored. On the other hand, if such frame arrives outside of DTX state,
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 when ECU logic is applied instead, our version retains the logic from ETSI
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 reference code in that codevector parameters from BFI frames are used if the
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 voiced vs unvoiced mode matches between the BFI frame and the saved frame used
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 by the ECU. This logic resides in the Rx front end that is shared between full
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 decoder and TFO transform implementations.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 There is, however, an extension to this logic original to Themyscira: if the
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 BFI word in the 22-word decoder input frame equals 2 instead of 1 (not allowed
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 in ETSI reference code where BFI is strictly a binary flag), the frame is
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 treated as BFI-no-data and no parameter bits are ever used in any state.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 Higher-level RTP input functions, described later in this article, feed this
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 BFI=2 code to the speech decoder or TFO transform engine when RTP input is BFI
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 without payload bits.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 Representation and handling of invalid SID
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 ------------------------------------------
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 If a decoder input frame in the canonical 22-word *.dec format has indicators
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 set to either SID=1 (irrespective of other flags) or SID=2 with either BFI or
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 UFI nonzero, that input frame is invalid SID per GSM 06.41. All 18 speech
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 parameters are fully ignored in such frames, always.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 In RTP transport these invalid SID frames can be represented only in TW-TS-002,
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 not in either of the two non-Themyscira standards. TW-TS-002 offers the option
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 of either including or omitting payload bits in invalid SID packets - however,
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 if invalid SID payload bits are included, they are ignored by our speech decoder
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 and TFO transform engines.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 Libgsmhr1 general usage
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 =======================
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 The external public interface to Themyscira libgsmhr1 consists of a single
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 header file <tw_gsmhr.h>; it should be installed in some system include
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 directory.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 The dialect of C used by all Themyscira GSM codec libraries is ANSI C (function
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 prototypes), const qualifier is used where appropriate, and the interface is
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 defined in terms of <stdint.h> types; <tw_gsmhr.h> includes <stdint.h>.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 State allocation and freeing
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 ============================
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 In order to use the speech encoder, you will need to allocate an encoder state
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 structure, and to use the speech decoder, you will need to allocate a decoder
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 state structure. The same goes for the stateful TFO transform. The necessary
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 state allocation functions are:
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 struct gsmhr_encoder_state *gsmhr_encoder_create(int dtx);
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 struct gsmhr_decoder_state *gsmhr_decoder_create(void);
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 struct gsmhr_rxfe_state *gsmhr_rxfe_create(void); /* TFO transform */
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 struct gsmhr_encoder_state, struct gsmhr_decoder_state and struct
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122 gsmhr_rxfe_state are opaque structures to library users: you only get pointers
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 which you remember and pass around, but <tw_gsmhr.h> does not give you full
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124 definitions of these structs. As a library user, you ordinarily don't even
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 need to know the size of these structs, hence the necessary malloc() operation
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126 happens inside gsmhr_encoder_create(), gsmhr_decoder_create() and
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 gsmhr_rxfe_create() functions. (But see the following section regarding
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 alternative memory allocation schemes.) However, each structure is malloc'ed
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129 as a single chunk, hence when you are done with it, simply call free() to
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 relinquish each encoder, decoder or TFO state instance.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132 gsmhr_encoder_create(), gsmhr_decoder_create() and gsmhr_rxfe_create() functions
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 can fail if the malloc() call inside fails, in which case these libgsmhr1
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 functions return NULL.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136 The dtx argument to gsmhr_encoder_create() is a Boolean flag represented as an
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137 int; it tells the GSM-HR speech encoder whether it should operate with DTX
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138 enabled (run GSM 06.42 VAD and emit SID frames instead of speech frames per
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 GSM 06.41) or DTX disabled (skip VAD and always emit speech frames).
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141 It should be noted that the original GSM-HR speech encoder from ETSI always runs
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142 GSM 06.42 VAD algorithm, whether DTX is enabled or disabled; if DTX is disabled,
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143 VAD flag is forced to 1, but all VAD and Tx DTX logic still executes and burns
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 up CPU cycles. Due to work scope limits described in HR-codec-limits article,
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145 this poor design from ETSI has been retained at the present. However, the API
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146 design allows DTX enable-or-disable flag to be changed only with a full reset
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147 of the speech encoder, rather than per frame - this API design thus prepares
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 for the possibility of cleaning up this implementation in the future and
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149 executing VAD and Tx DTX code only when DTX is enabled in the speech encoding
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
150 direction.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
152 State reset functions
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153 =====================
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155 void gsmhr_encoder_reset(struct gsmhr_encoder_state *st, int dtx);
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 void gsmhr_decoder_reset(struct gsmhr_decoder_state *st);
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157 void gsmhr_rxfe_reset(struct gsmhr_rxfe_state *st);
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159 Each of these functions resets the state of the corresponding element to its
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160 initial or "home" state. Home states for the standard speech encoder and
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 decoder are given in GSM 06.20 sections 5.5 and 5.6, respectively; the home
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 state for the separated-out RxFE block (used for TFO transform) is a subset of
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163 the full speech decoder home state as relevant to the reduced functionality.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
165 The following const "variables" are exported by the library in order to
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
166 facilitate alternative memory allocation schemes:
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
167
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 extern const unsigned gsmhr_encoder_state_size;
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169 extern const unsigned gsmhr_decoder_state_size;
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170 extern const unsigned gsmhr_rxfe_state_size;
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
172 Using these const "variables", an application can allocate buffers of the
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 correct size for each state structure, and then initialize each newly allocated
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174 state structure with gsmhr_*_reset(), as an alternative to gsmhr_*_create()
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175 functions. Each of the standard gsmhr_*_create() functions allocates a buffer
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
176 of the correct size using standard malloc(), then initializes it with the
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177 corresponding gsmhr_*_reset() function - hence the lower-level approach can be
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178 used by applications that desire some other memory allocation scheme than
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179 standard malloc().
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
180
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
181 Using the speech encoder
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
182 ========================
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
183
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 To encode one 20 ms audio frame per GSM-HR, call gsmhr_encode_frame():
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
185
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
186 void gsmhr_encode_frame(struct gsmhr_encoder_state *st, const int16_t *pcm,
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
187 int16_t *param);
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
188
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
189 You need to provide an encoder state structure allocated earlier with
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
190 gsmhr_encoder_create(), a block of 160 linear PCM samples, and an output buffer
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
191 of 20 (GSMHR_NUM_PARAMS_ENC) 16-bit words into which the encoded GSM-HR frame
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
192 will be written. The encoded frame format emitted by this function is the same
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193 as in the reference implementation from ETSI: 18 words of speech parameters
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194 followed by VAD and SP flags. Stateless format conversion functions described
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195 later in this document can be used to emit more commonly used RTP formats.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
196
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197 The mandatory encoder homing function is included: if the input frame matches
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
198 the encoder homing frame, the encoder state is reset to the home state at the
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199 end of gsmhr_encode_frame() processing.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
201 Using the speech decoder
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
202 ========================
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
203
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
204 Our speech decoder main function is:
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
205
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
206 void gsmhr_decode_frame(struct gsmhr_decoder_state *st, const int16_t *param,
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
207 int16_t *pcm);
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
208
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
209 The input frame format is the canonical one from ETSI: 22 (GSMHR_NUM_PARAMS_DEC)
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
210 16-bit words providing speech parameters followed by BFI, UFI, SID and TAF
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
211 metadata flags. In normal operation, this internal canonical form of speech
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
212 decoder input will be provided by one of the stateless format conversion
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
213 functions in the same libgsmhr1.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
214
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
215 Important note: the parameter frame input to this function is expected to be
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
216 valid, i.e., it is NOT subjected to explicit validation checks! If your
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
217 application reads *.dec files or otherwise receives this format directly from
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
218 some external source (as opposed to output from one of our own format conversion
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
219 functions), you need to validate these bits with gsmhr_check_decoder_params()
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
220 before feeding them to the decoder engine!
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
221
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
222 This speech decoder function includes all mandatory logic for decoder homing:
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
223 special handling of the homed state, decoder homing frame checks of both full
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
224 and partial (to the first subframe) kinds, internal state reset and EHF output.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
225
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
226 TFO transform function
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
227 ======================
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
228
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
229 To operate our TFO transform for GSM-HR codec, create a standalone RxFE state
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
230 structure (use gsmhr_rxfe_create() or your own allocation followed by
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
231 gsmhr_rxfe_reset()) and then call this function for every frame to be processed:
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
232
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
233 void gsmhr_tfo_xfrm(struct gsmhr_rxfe_state *st, int dtxd, const int16_t *ul,
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
234 int16_t *dl);
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
235
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
236 UL Rx input has the same form as input to gsmhr_decode_frame(), and the same
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
237 caveats apply in terms of validation checks. DL Tx output is emitted in the
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
238 same form as gsmhr_encode_frame() output, complete with VAD and SP flags. VAD
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
239 output should be considered a dummy, but SP output flag is valid: 1 in the case
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
240 of a speech frame or 0 in the case of a SID frame; the latter is possible only
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
241 when DTXd is enabled.
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
242
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
243 DTXd control: dtxd argument to gsmhr_tfo_xfrm() tells the transform if it should
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
244 emit both speech and SID frames or speech frames only, corresponding to DTXd
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
245 flag in TRAU-UL frames that affects both speech encoder and TFO transform
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
246 functions in traditional TRAUs. This flag can be changed mid-session: as
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
247 explained in HR-codec-Rx-logic article, our implementation of TFO transform
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
248 proceeds by applying classic Rx front end processing that only emits speech
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
249 frames, and then replacing output with SID frames under certain conditions if
7fc57e2a6784 beginning of GSM-HR documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
250 DTXd is enabled.
633
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
251
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
252 Stateless utility functions
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
253 ===========================
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
254
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
255 All functions in this section are stateless (no encoder, decoder or RxFE state
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
256 structure is needed); they merely manipulate data formats.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
257
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
258 void gsmhr_pack_ts101318(const int16_t *param, uint8_t *payload);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
259
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
260 This function converts a 112-bit GSM-HR codec frame from an array of speech
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
261 parameters (18 16-bit words) into the packed format of ETSI TS 101 318, which
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
262 is a buffer of 14 octets with every bit used for payload. Any extraneous bits
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
263 in input 16-bit words (beyond the size of each parameter in bits) are ignored.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
264
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
265 void gsmhr_unpack_ts101318(const uint8_t *payload, int16_t *param);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
266
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
267 This function converts a 112-bit GSM-HR codec frame from the packed format of
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
268 TS 101 318 into an array of 18 speech parameters.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
269
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
270 void gsmhr_encoder_twts002_out(const int16_t *param, uint8_t *payload);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
271
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
272 This function converts a cod-style frame (output from gsmhr_encode_frame() or
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
273 gsmhr_tfo_xfrm(), or read from an ETSI *.cod file) into TW-TS-002 format. The
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
274 output is always 15 octets long (the buffer must have this much room), and is
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
275 valid per both RFC 5993 and TW-TS-002 specs. The only two possible frame types
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
276 in this context are good speech and good SID, distinguished by SP flag in the
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
277 cod-style input and by FT field in RFC 5993 output.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
278
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
279 int gsmhr_decoder_twts002_in(const uint8_t *payload, int16_t *param);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
280
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
281 This function reads a super-5993 frame in TW-TS-002 format from a buffer and
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
282 converts it into the required form for input to gsmhr_decode_frame() or
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
283 gsmhr_tfo_xfrm(), which is an extended form of ETSI's *.dec format. The input
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
284 must be a valid super-5993 in the following sense:
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
285
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
286 * The first octet in the buffer must be valid ToC per TW-TS-002 section 5.1;
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
287
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
288 * F bit in this ToC octet must be cleared;
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
289
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
290 * FT field must equal 0, 1, 2, 6 or 7 per TW-TS-002 section 5.2;
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
291
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
292 * If FT equals 0, 2 or 6, the ToC octet must be followed by 14 octets of frame
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
293 payload.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
294
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
295 If any of these rules are violated, gsmhr_decoder_twts002_in() returns a
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
296 negative value (-1 if F bit is set or -2 if FT is invalid) and does not write
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
297 anything into the output array. Otherwise, the function returns 0 (indicating
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
298 success) and the output array is filled as follows:
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
299
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
300 * For frame types 0, 2 and 6, the 18 speech parameters are filled from the
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
301 TS-101-318-like payload portion of super-5993 input.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
302
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
303 * For frame types 1 and 7, the 18 speech parameters are set to all zeros, with
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
304 the expectation that gsmhr_decode_frame() or gsmhr_tfo_xfrm() will ignore
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
305 them. Please note that "verbose" invalid SID bits that may be present in
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
306 TW-TS-002 transport are ignored.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
307
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
308 * The 4 metadata flags BFI, UFI, SID and TAF are set based on FT and the
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
309 additional ToC flags defined in TW-TS-002 section 5.3.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
310
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
311 * Themyscira extension of BFI=2, described earlier in this document, is used
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
312 to represent FT=7.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
313
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
314 * Invalid SID frames (FT=1) are converted to BFI=1 SID=1.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
315
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
316 int gsmhr_rtp_in_preen(const uint8_t *rtp_in, unsigned rtp_in_len,
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
317 uint8_t *canon_pl);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
318
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
319 This function performs initial processing of RTP input that is expected to be
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
320 one of the defined RTP formats for GSM-HR codec. It accepts all possibilities
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
321 of TW-TS-002, RFC 5993 or TS 101 318 (listed in ThemWi order of preference) and
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
322 writes canonical TW-TS-002 super-5993 format into a buffer. The output buffer
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
323 must have 15 bytes of space, and the frame written into this buffer will ALWAYS
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
324 be a valid input to gsmhr_decoder_twts002_in() function described above.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
325
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
326 The input arguments are RTP payload and its length. The return value is 0 if
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
327 RTP input was in a recognized format, or -1 if it is invalid. In the case of
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
328 invalid RTP input, the output is filled with ToC of 0x70 (BFI with no data) -
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
329 the output is always valid.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
330
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
331 Zero-length RTP payloads are acceptable; if rtp_in_len is 0, then rtp_in pointer
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
332 may be NULL. The output in this case is filled with ToC of 0x70 (BFI with no
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
333 data), but the return value is 0, indicating success. The intent is that truly
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
334 invalid RTP payloads are error events which should be counted, while NULL input
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
335 is a normal occurrence when ThemWi jitter buffer (twjit) does not hold a
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
336 previously received RTP packet that maps to the current tick. (Actually
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
337 transmitted RTP packets with a zero-length payloads are also possible: they are
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
338 ThemWi preferred alternative to IETF approach of intentional gaps in the RTP
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
339 stream.)
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
340
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
341 int gsmhr_rtp_in_direct(const uint8_t *rtp_in, unsigned rtp_in_len,
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
342 int16_t *param);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
343
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
344 This function is fully equivalent to calling first gsmhr_rtp_in_preen(), then
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
345 gsmhr_decoder_twts002_in(). It is however slightly more efficient, as it avoids
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
346 the intermediate buffer and some copying. The return value is the same as
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
347 gsmhr_rtp_in_preen(), and just like with that function, the output is always
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
348 valid.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
349
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
350 Reading *.cod and *.dec files
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
351 -----------------------------
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
352
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
353 The most native representation format for GSM-HR codec frames in libgsmhr1 is
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
354 arrays of broken-down speech parameters. However, unlike TS 101 318 format in
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
355 which every possible bit pattern is a plausible GSM-HR codec frame, an array of
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
356 broken-down parameters that purports to be a GSM-HR frame can contain garbage.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
357 The additional metadata flags in the canonical decoder input format can also
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
358 contain garbage - which our speech decoder and TFO transform engines are NOT
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
359 prepared for! There is no potential for malfunction if these arrays of
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
360 parameters and metadata flags come only from libgsmhr1 functions - but if an
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
361 application needs to read *.cod or *.dec files, or otherwise accept external
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
362 input in any of these formats, then an explicit validation step is required.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
363
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
364 int gsmhr_check_common_params(const int16_t *params);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
365
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
366 This function examines an array of 18 codec parameters in the int16_t
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
367 representation used in this library, and checks if the unused upper bits of
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
368 each int16_t word are cleared as they should be. The return value is 0 if the
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
369 frame is valid or -1 if some extraneous high bits are set.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
370
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
371 int gsmhr_check_encoder_params(const int16_t *params);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
372
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
373 This function examines a frame of 20 int16_t words that corresponds to GSM-HR
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
374 encoder output format, and checks if the unused upper bits of each int16_t word
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
375 are cleared as they should be. This function should be used when reading from
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
376 ETSI-format *.cod files, to guard against reading garbage or wrong endian. The
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
377 return value is 0 if the frame is valid or -1 if some extraneous high bits are
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
378 set.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
379
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
380 int gsmhr_check_decoder_params(const int16_t *params);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
381
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
382 This function examines a frame of 22 int16_t words that corresponds to GSM-HR
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
383 decoder input format, and checks if the unused upper bits of each int16_t word
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
384 are cleared as they should be. This function should be used when reading from
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
385 ETSI-format *.dec files, to guard against reading garbage or wrong endian. The
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
386 return value is 0 if the frame is valid or -1 if some extraneous high bits are
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
387 set. Both BFI and SID words are limited to range [0,2], i.e., Themyscira BFI=2
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
388 extension is accepted.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
389
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
390 SID field manipulation
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
391 ----------------------
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
392
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
393 Unlike FR and EFR, GSM-HR codec lacks fixed rules for Rx frame classification
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
394 as valid SID, invalid SID or non-SID speech. The BTS makes this classification
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
395 decision according to its internal private rules, and the SID flag then needs
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
396 to be carried out of band in Abis, Ater and TFO. GSM 08.61 and TW-TS-002
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
397 (extended 5993) formats provide the necessary out-of-band SID indication, but
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
398 the bare format of TS 101 318 does not. Therefore, the only kind of GSM-HR SID
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
399 that can be represented in TS 101 318 format are perfect, 100% error-free SID
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
400 frames in which all 79 bits of the SID field are set to 1.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
401
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
402 int gsmhr_ts101318_is_perfect_sid(const uint8_t *payload);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
403
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
404 This function checks the given TS 101 318 payload for the possibility of
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
405 perfect SID. The return value is 2 (GSM 06.41 code for valid SID) if the frame
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
406 is indeed a perfect SID, or 0 (GSM 06.41 code for non-SID speech) otherwise.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
407
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
408 void gsmhr_ts101318_set_sid_codeword(uint8_t *payload);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
409
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
410 This function sets all 79 bits of the SID field to 1s, forming a perfect SID
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
411 frame in the 14-byte buffer. The first 33 bits that carry R0 and LPC parameters
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
412 must already be filled correctly.
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
413
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
414 void gsmhr_set_sid_cw_params(int16_t *params);
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
415
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
416 This function fills parameters 4 through 17 of generated SID frames, setting
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
417 them to the required SID codeword. It can also be used to transform a speech
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
418 frame into a SID frame with the same R0 and LPC parameters. It is logically
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
419 equivalent to gsmhr_ts101318_set_sid_codeword(), but operates on the array of
3ab76caba41c doc/HR-codec-library: document stateless utility functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 632
diff changeset
420 parameters form, rather than TS 101 318 packed format.
635
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
421
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
422 Public constant definitions
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
423 ===========================
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
424
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
425 Our public header file <tw_gsmhr.h> provides these constant definitions, which
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
426 should be self-explanatory:
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
427
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
428 #define GSMHR_NUM_PARAMS 18 /* actual codec parameters */
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
429 #define GSMHR_NUM_PARAMS_ENC 20 /* output from the encoder */
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
430 #define GSMHR_NUM_PARAMS_DEC 22 /* input to the decoder */
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
431
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
432 #define GSMHR_FRAME_LEN_RPF 14 /* raw packed format */
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
433 #define GSMHR_FRAME_LEN_5993 15 /* RFC 5993 and TW-TS-002 */
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
434
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
435 Public const data items
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
436 =======================
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
437
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
438 The spec-defined decoder homing frame for GSM-HR is provided in both native
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
439 (array of parameters) and packed (TS 101 318) formats:
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
440
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
441 extern const int16_t gsmhr_dhf_params[GSMHR_NUM_PARAMS];
723265aea9f8 doc/HR-codec-library: finish library documentation
Mychaela Falconia <falcon@freecalypso.org>
parents: 633
diff changeset
442 extern const uint8_t gsmhr_dhf_ts101318[GSMHR_FRAME_LEN_RPF];