1/*
2 *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11/*
12 * entropy_coding.h
13 *
14 * This header file declares all of the functions used to arithmetically
15 * encode the iSAC bistream
16 *
17 */
18
19#ifndef WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_SOURCE_ENTROPY_CODING_H_
20#define WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_SOURCE_ENTROPY_CODING_H_
21
22#include "settings.h"
23#include "structs.h"
24
25/******************************************************************************
26 * WebRtcIsac_DecodeSpec()
27 * Decode real and imaginary part of the DFT coefficients, given a bit-stream.
28 * The decoded DFT coefficient can be transformed to time domain by
29 * WebRtcIsac_Time2Spec().
30 *
31 * Input:
32 *  - streamdata            : pointer to a stucture containg the encoded
33 *                            data and theparameters needed for entropy
34 *                            coding.
35 *  - AvgPitchGain_Q12      : average pitch-gain of the frame. This is only
36 *                            relevant for 0-4 kHz band, and the input value is
37 *                            not used in other bands.
38 *  - band                  : specifies which band's DFT should be decoded.
39 *
40 * Output:
41 *   - *fr                  : pointer to a buffer where the real part of DFT
42 *                            coefficients are written to.
43 *   - *fi                  : pointer to a buffer where the imaginary part
44 *                            of DFT coefficients are written to.
45 *
46 * Return value             : < 0 if an error occures
47 *                              0 if succeeded.
48 */
49int WebRtcIsac_DecodeSpec(Bitstr* streamdata, WebRtc_Word16 AvgPitchGain_Q12,
50                          enum ISACBand band, double* fr, double* fi);
51
52/******************************************************************************
53 * WebRtcIsac_EncodeSpec()
54 * Encode real and imaginary part of the DFT coefficients into the given
55 * bit-stream.
56 *
57 * Input:
58 *  - *fr                   : pointer to a buffer where the real part of DFT
59 *                            coefficients are written to.
60 *  - *fi                   : pointer to a buffer where the imaginary part
61 *                            of DFT coefficients are written to.
62 *  - AvgPitchGain_Q12      : average pitch-gain of the frame. This is only
63 *                            relevant for 0-4 kHz band, and the input value is
64 *                            not used in other bands.
65 *  - band                  : specifies which band's DFT should be decoded.
66 *
67 * Output:
68 *  - streamdata            : pointer to a stucture containg the encoded
69 *                            data and theparameters needed for entropy
70 *                            coding.
71 *
72 * Return value             : < 0 if an error occures
73 *                              0 if succeeded.
74 */
75int WebRtcIsac_EncodeSpec(const WebRtc_Word16* fr, const WebRtc_Word16* fi,
76                          WebRtc_Word16 AvgPitchGain_Q12, enum ISACBand band,
77                          Bitstr* streamdata);
78
79/* decode & dequantize LPC Coef */
80int WebRtcIsac_DecodeLpcCoef(Bitstr* streamdata, double* LPCCoef);
81int WebRtcIsac_DecodeLpcCoefUB(Bitstr* streamdata, double* lpcVecs,
82                               double* percepFilterGains,
83                               WebRtc_Word16 bandwidth);
84
85int WebRtcIsac_DecodeLpc(Bitstr* streamdata, double* LPCCoef_lo,
86                         double* LPCCoef_hi);
87
88/* quantize & code LPC Coef */
89void WebRtcIsac_EncodeLpcLb(double* LPCCoef_lo, double* LPCCoef_hi,
90                            Bitstr* streamdata, ISAC_SaveEncData_t* encData);
91
92void WebRtcIsac_EncodeLpcGainLb(double* LPCCoef_lo, double* LPCCoef_hi,
93                                Bitstr* streamdata,
94                                ISAC_SaveEncData_t* encData);
95
96/******************************************************************************
97 * WebRtcIsac_EncodeLpcUB()
98 * Encode LPC parameters, given as A-polynomial, of upper-band. The encoding
99 * is performed in LAR domain.
100 * For the upper-band, we compute and encode LPC of some sub-frames, LPC of
101 * other sub-frames are computed by linear interpolation, in LAR domain. This
102 * function performs the interpolation and returns the LPC of all sub-frames.
103 *
104 * Inputs:
105 *  - lpcCoef               : a buffer containing A-polynomials of sub-frames
106 *                            (excluding first coefficient that is 1).
107 *  - bandwidth             : specifies if the codec is operating at 0-12 kHz
108 *                            or 0-16 kHz mode.
109 *
110 * Input/output:
111 *  - streamdata            : pointer to a structure containing the encoded
112 *                            data and the parameters needed for entropy
113 *                            coding.
114 *
115 * Output:
116 *  - interpolLPCCoeff      : Decoded and interpolated LPC (A-polynomial)
117 *                            of all sub-frames.
118 *                            If LP analysis is of order K, and there are N
119 *                            sub-frames then this is a buffer of size
120 *                            (k + 1) * N, each vector starts with the LPC gain
121 *                            of the corresponding sub-frame. The LPC gains
122 *                            are encoded and inserted after this function is
123 *                            called. The first A-coefficient which is 1 is not
124 *                            included.
125 *
126 * Return value             : 0 if encoding is successful,
127 *                           <0 if failed to encode.
128 */
129WebRtc_Word16 WebRtcIsac_EncodeLpcUB(double* lpcCoeff, Bitstr* streamdata,
130                                     double* interpolLPCCoeff,
131                                     WebRtc_Word16 bandwidth,
132                                     ISACUBSaveEncDataStruct* encData);
133
134/******************************************************************************
135 * WebRtcIsac_DecodeInterpolLpcUb()
136 * Decode LPC coefficients and interpolate to get the coefficients fo all
137 * sub-frmaes.
138 *
139 * Inputs:
140 *  - bandwidth             : spepecifies if the codec is in 0-12 kHz or
141 *                            0-16 kHz mode.
142 *
143 * Input/output:
144 *  - streamdata            : pointer to a stucture containg the encoded
145 *                            data and theparameters needed for entropy
146 *                            coding.
147 *
148 * Output:
149 *  - percepFilterParam     : Decoded and interpolated LPC (A-polynomial) of
150 *                            all sub-frames.
151 *                            If LP analysis is of order K, and there are N
152 *                            sub-frames then this is a buffer of size
153 *                            (k + 1) * N, each vector starts with the LPC gain
154 *                            of the corresponding sub-frame. The LPC gains
155 *                            are encoded and inserted after this function is
156 *                            called. The first A-coefficient which is 1 is not
157 *                            included.
158 *
159 * Return value             : 0 if encoding is successful,
160 *                           <0 if failed to encode.
161 */
162WebRtc_Word16 WebRtcIsac_DecodeInterpolLpcUb(Bitstr* streamdata,
163                                             double* percepFilterParam,
164                                             WebRtc_Word16 bandwidth);
165
166/* Decode & dequantize RC */
167int WebRtcIsac_DecodeRc(Bitstr* streamdata, WebRtc_Word16* RCQ15);
168
169/* Quantize & code RC */
170void WebRtcIsac_EncodeRc(WebRtc_Word16* RCQ15, Bitstr* streamdata);
171
172/* Decode & dequantize squared Gain */
173int WebRtcIsac_DecodeGain2(Bitstr* streamdata, WebRtc_Word32* Gain2);
174
175/* Quantize & code squared Gain (input is squared gain) */
176int WebRtcIsac_EncodeGain2(WebRtc_Word32* gain2, Bitstr* streamdata);
177
178void WebRtcIsac_EncodePitchGain(WebRtc_Word16* PitchGains_Q12,
179                                Bitstr* streamdata,
180                                ISAC_SaveEncData_t* encData);
181
182void WebRtcIsac_EncodePitchLag(double* PitchLags, WebRtc_Word16* PitchGain_Q12,
183                               Bitstr* streamdata, ISAC_SaveEncData_t* encData);
184
185int WebRtcIsac_DecodePitchGain(Bitstr* streamdata,
186                               WebRtc_Word16* PitchGain_Q12);
187int WebRtcIsac_DecodePitchLag(Bitstr* streamdata, WebRtc_Word16* PitchGain_Q12,
188                              double* PitchLag);
189
190int WebRtcIsac_DecodeFrameLen(Bitstr* streamdata, WebRtc_Word16* framelength);
191int WebRtcIsac_EncodeFrameLen(WebRtc_Word16 framelength, Bitstr* streamdata);
192int WebRtcIsac_DecodeSendBW(Bitstr* streamdata, WebRtc_Word16* BWno);
193void WebRtcIsac_EncodeReceiveBw(int* BWno, Bitstr* streamdata);
194
195/* Step-down */
196void WebRtcIsac_Poly2Rc(double* a, int N, double* RC);
197
198/* Step-up */
199void WebRtcIsac_Rc2Poly(double* RC, int N, double* a);
200
201void WebRtcIsac_TranscodeLPCCoef(double* LPCCoef_lo, double* LPCCoef_hi,
202                                 int* index_g);
203
204
205/******************************************************************************
206 * WebRtcIsac_EncodeLpcGainUb()
207 * Encode LPC gains of sub-Frames.
208 *
209 * Input/outputs:
210 *  - lpGains               : a buffer which contains 'SUBFRAME' number of
211 *                            LP gains to be encoded. The input values are
212 *                            overwritten by the quantized values.
213 *  - streamdata            : pointer to a stucture containg the encoded
214 *                            data and theparameters needed for entropy
215 *                            coding.
216 *
217 * Output:
218 *  - lpcGainIndex          : quantization indices for lpc gains, these will
219 *                            be stored to be used  for FEC.
220 */
221void WebRtcIsac_EncodeLpcGainUb(double* lpGains, Bitstr* streamdata,
222                                int* lpcGainIndex);
223
224
225/******************************************************************************
226 * WebRtcIsac_EncodeLpcGainUb()
227 * Store LPC gains of sub-Frames in 'streamdata'.
228 *
229 * Input:
230 *  - lpGains               : a buffer which contains 'SUBFRAME' number of
231 *                            LP gains to be encoded.
232 * Input/outputs:
233 *  - streamdata            : pointer to a stucture containg the encoded
234 *                            data and theparameters needed for entropy
235 *                            coding.
236 *
237 */
238void WebRtcIsac_StoreLpcGainUb(double* lpGains, Bitstr* streamdata);
239
240
241/******************************************************************************
242 * WebRtcIsac_DecodeLpcGainUb()
243 * Decode the LPC gain of sub-frames.
244 *
245 * Input/output:
246 *  - streamdata            : pointer to a stucture containg the encoded
247 *                            data and theparameters needed for entropy
248 *                            coding.
249 *
250 * Output:
251 *  - lpGains               : a buffer where decoded LPC gians will be stored.
252 *
253 * Return value             : 0 if succeeded.
254 *                           <0 if failed.
255 */
256WebRtc_Word16 WebRtcIsac_DecodeLpcGainUb(double* lpGains, Bitstr* streamdata);
257
258
259/******************************************************************************
260 * WebRtcIsac_EncodeBandwidth()
261 * Encode if the bandwidth of encoded audio is 0-12 kHz or 0-16 kHz.
262 *
263 * Input:
264 *  - bandwidth             : an enumerator specifying if the codec in is
265 *                            0-12 kHz or 0-16 kHz mode.
266 *
267 * Input/output:
268 *  - streamdata            : pointer to a stucture containg the encoded
269 *                            data and theparameters needed for entropy
270 *                            coding.
271 *
272 * Return value             : 0 if succeeded.
273 *                           <0 if failed.
274 */
275WebRtc_Word16 WebRtcIsac_EncodeBandwidth(enum ISACBandwidth bandwidth,
276                                         Bitstr* streamData);
277
278
279/******************************************************************************
280 * WebRtcIsac_DecodeBandwidth()
281 * Decode the bandwidth of the encoded audio, i.e. if the bandwidth is 0-12 kHz
282 * or 0-16 kHz.
283 *
284 * Input/output:
285 *  - streamdata            : pointer to a stucture containg the encoded
286 *                            data and theparameters needed for entropy
287 *                            coding.
288 *
289 * Output:
290 *  - bandwidth             : an enumerator specifying if the codec is in
291 *                            0-12 kHz or 0-16 kHz mode.
292 *
293 * Return value             : 0 if succeeded.
294 *                           <0 if failed.
295 */
296WebRtc_Word16 WebRtcIsac_DecodeBandwidth(Bitstr* streamData,
297                                         enum ISACBandwidth* bandwidth);
298
299
300/******************************************************************************
301 * WebRtcIsac_EncodeJitterInfo()
302 * Decode the jitter information.
303 *
304 * Input/output:
305 *  - streamdata            : pointer to a stucture containg the encoded
306 *                            data and theparameters needed for entropy
307 *                            coding.
308 *
309 * Input:
310 *  - jitterInfo            : one bit of info specifying if the channel is
311 *                            in high/low jitter. Zero indicates low jitter
312 *                            and one indicates high jitter.
313 *
314 * Return value             : 0 if succeeded.
315 *                           <0 if failed.
316 */
317WebRtc_Word16 WebRtcIsac_EncodeJitterInfo(WebRtc_Word32 jitterIndex,
318                                          Bitstr* streamData);
319
320
321/******************************************************************************
322 * WebRtcIsac_DecodeJitterInfo()
323 * Decode the jitter information.
324 *
325 * Input/output:
326 *  - streamdata            : pointer to a stucture containg the encoded
327 *                            data and theparameters needed for entropy
328 *                            coding.
329 *
330 * Output:
331 *  - jitterInfo            : one bit of info specifying if the channel is
332 *                            in high/low jitter. Zero indicates low jitter
333 *                            and one indicates high jitter.
334 *
335 * Return value             : 0 if succeeded.
336 *                           <0 if failed.
337 */
338WebRtc_Word16 WebRtcIsac_DecodeJitterInfo(Bitstr* streamData,
339                                          WebRtc_Word32* jitterInfo);
340
341#endif /* WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_SOURCE_ENTROPY_CODING_H_ */
342