1 /*
2  *  Copyright (c) 2011 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 #ifndef MODULES_AUDIO_CODING_CODECS_ISAC_FIX_INCLUDE_ISACFIX_H_
12 #define MODULES_AUDIO_CODING_CODECS_ISAC_FIX_INCLUDE_ISACFIX_H_
13 
14 #include <stddef.h>
15 
16 #include "modules/audio_coding/codecs/isac/bandwidth_info.h"
17 
18 typedef struct {
19   void* dummy;
20 } ISACFIX_MainStruct;
21 
22 #if defined(__cplusplus)
23 extern "C" {
24 #endif
25 
26 /****************************************************************************
27  * WebRtcIsacfix_Create(...)
28  *
29  * This function creates an ISAC instance, which will contain the state
30  * information for one coding/decoding channel.
31  *
32  * Input:
33  *      - *ISAC_main_inst   : a pointer to the coder instance.
34  *
35  * Return value             : 0 - Ok
36  *                           -1 - Error
37  */
38 
39 int16_t WebRtcIsacfix_Create(ISACFIX_MainStruct** ISAC_main_inst);
40 
41 /****************************************************************************
42  * WebRtcIsacfix_Free(...)
43  *
44  * This function frees the ISAC instance created at the beginning.
45  *
46  * Input:
47  *      - ISAC_main_inst    : a ISAC instance.
48  *
49  * Return value             :  0 - Ok
50  *                            -1 - Error
51  */
52 
53 int16_t WebRtcIsacfix_Free(ISACFIX_MainStruct* ISAC_main_inst);
54 
55 /****************************************************************************
56  * WebRtcIsacfix_EncoderInit(...)
57  *
58  * This function initializes an ISAC instance prior to the encoder calls.
59  *
60  * Input:
61  *     - ISAC_main_inst     : ISAC instance.
62  *     - CodingMode         : 0 - Bit rate and frame length are automatically
63  *                                adjusted to available bandwidth on
64  *                                transmission channel.
65  *                            1 - User sets a frame length and a target bit
66  *                                rate which is taken as the maximum short-term
67  *                                average bit rate.
68  *
69  * Return value             :  0 - Ok
70  *                            -1 - Error
71  */
72 
73 int16_t WebRtcIsacfix_EncoderInit(ISACFIX_MainStruct* ISAC_main_inst,
74                                   int16_t CodingMode);
75 
76 /****************************************************************************
77  * WebRtcIsacfix_Encode(...)
78  *
79  * This function encodes 10ms frame(s) and inserts it into a package.
80  * Input speech length has to be 160 samples (10ms). The encoder buffers those
81  * 10ms frames until it reaches the chosen Framesize (480 or 960 samples
82  * corresponding to 30 or 60 ms frames), and then proceeds to the encoding.
83  *
84  * Input:
85  *      - ISAC_main_inst    : ISAC instance.
86  *      - speechIn          : input speech vector.
87  *
88  * Output:
89  *      - encoded           : the encoded data vector
90  *
91  * Return value             : >0 - Length (in bytes) of coded data
92  *                             0 - The buffer didn't reach the chosen framesize
93  *                                 so it keeps buffering speech samples.
94  *                            -1 - Error
95  */
96 
97 int WebRtcIsacfix_Encode(ISACFIX_MainStruct* ISAC_main_inst,
98                          const int16_t* speechIn,
99                          uint8_t* encoded);
100 
101 /****************************************************************************
102  * WebRtcIsacfix_DecoderInit(...)
103  *
104  * This function initializes an ISAC instance prior to the decoder calls.
105  *
106  * Input:
107  *  - ISAC_main_inst : ISAC instance.
108  */
109 
110 void WebRtcIsacfix_DecoderInit(ISACFIX_MainStruct* ISAC_main_inst);
111 
112 /****************************************************************************
113  * WebRtcIsacfix_UpdateBwEstimate1(...)
114  *
115  * This function updates the estimate of the bandwidth.
116  *
117  * Input:
118  *      - ISAC_main_inst    : ISAC instance.
119  *      - encoded           : encoded ISAC frame(s).
120  *      - packet_size       : size of the packet in bytes.
121  *      - rtp_seq_number    : the RTP number of the packet.
122  *      - arr_ts            : the arrival time of the packet (from NetEq)
123  *                            in samples.
124  *
125  * Return value             : 0 - Ok
126  *                           -1 - Error
127  */
128 
129 int16_t WebRtcIsacfix_UpdateBwEstimate1(ISACFIX_MainStruct* ISAC_main_inst,
130                                         const uint8_t* encoded,
131                                         size_t packet_size,
132                                         uint16_t rtp_seq_number,
133                                         uint32_t arr_ts);
134 
135 /****************************************************************************
136  * WebRtcIsacfix_UpdateBwEstimate(...)
137  *
138  * This function updates the estimate of the bandwidth.
139  *
140  * Input:
141  *      - ISAC_main_inst    : ISAC instance.
142  *      - encoded           : encoded ISAC frame(s).
143  *      - packet_size       : size of the packet in bytes.
144  *      - rtp_seq_number    : the RTP number of the packet.
145  *      - send_ts           : the send time of the packet from RTP header,
146  *                            in samples.
147  *      - arr_ts            : the arrival time of the packet (from NetEq)
148  *                            in samples.
149  *
150  * Return value             :  0 - Ok
151  *                            -1 - Error
152  */
153 
154 int16_t WebRtcIsacfix_UpdateBwEstimate(ISACFIX_MainStruct* ISAC_main_inst,
155                                        const uint8_t* encoded,
156                                        size_t packet_size,
157                                        uint16_t rtp_seq_number,
158                                        uint32_t send_ts,
159                                        uint32_t arr_ts);
160 
161 /****************************************************************************
162  * WebRtcIsacfix_Decode(...)
163  *
164  * This function decodes an ISAC frame. Output speech length
165  * will be a multiple of 480 samples: 480 or 960 samples,
166  * depending on the framesize (30 or 60 ms).
167  *
168  * Input:
169  *      - ISAC_main_inst    : ISAC instance.
170  *      - encoded           : encoded ISAC frame(s)
171  *      - len               : bytes in encoded vector
172  *
173  * Output:
174  *      - decoded           : The decoded vector
175  *
176  * Return value             : >0 - number of samples in decoded vector
177  *                            -1 - Error
178  */
179 
180 int WebRtcIsacfix_Decode(ISACFIX_MainStruct* ISAC_main_inst,
181                          const uint8_t* encoded,
182                          size_t len,
183                          int16_t* decoded,
184                          int16_t* speechType);
185 
186 /****************************************************************************
187  * WebRtcIsacfix_DecodePlc(...)
188  *
189  * This function conducts PLC for ISAC frame(s) in wide-band (16kHz sampling).
190  * Output speech length  will be "480*noOfLostFrames" samples
191  * that is equevalent of "30*noOfLostFrames" millisecond.
192  *
193  * Input:
194  *      - ISAC_main_inst    : ISAC instance.
195  *      - noOfLostFrames    : Number of PLC frames (480sample = 30ms)
196  *                            to produce
197  *                            NOTE! Maximum number is 2 (960 samples = 60ms)
198  *
199  * Output:
200  *      - decoded           : The decoded vector
201  *
202  * Return value             : Number of samples in decoded PLC vector
203  */
204 
205 size_t WebRtcIsacfix_DecodePlc(ISACFIX_MainStruct* ISAC_main_inst,
206                                int16_t* decoded,
207                                size_t noOfLostFrames);
208 
209 /****************************************************************************
210  * WebRtcIsacfix_ReadFrameLen(...)
211  *
212  * This function returns the length of the frame represented in the packet.
213  *
214  * Input:
215  *      - encoded           : Encoded bitstream
216  *      - encoded_len_bytes : Length of the bitstream in bytes.
217  *
218  * Output:
219  *      - frameLength       : Length of frame in packet (in samples)
220  *
221  */
222 
223 int16_t WebRtcIsacfix_ReadFrameLen(const uint8_t* encoded,
224                                    size_t encoded_len_bytes,
225                                    size_t* frameLength);
226 
227 /****************************************************************************
228  * WebRtcIsacfix_Control(...)
229  *
230  * This function sets the limit on the short-term average bit rate and the
231  * frame length. Should be used only in Instantaneous mode.
232  *
233  * Input:
234  *      - ISAC_main_inst    : ISAC instance.
235  *      - rate              : limit on the short-term average bit rate,
236  *                            in bits/second (between 10000 and 32000)
237  *      - framesize         : number of milliseconds per frame (30 or 60)
238  *
239  * Return value             : 0  - ok
240  *                           -1 - Error
241  */
242 
243 int16_t WebRtcIsacfix_Control(ISACFIX_MainStruct* ISAC_main_inst,
244                               int16_t rate,
245                               int framesize);
246 
247 void WebRtcIsacfix_SetInitialBweBottleneck(ISACFIX_MainStruct* ISAC_main_inst,
248                                            int bottleneck_bits_per_second);
249 
250 /****************************************************************************
251  * WebRtcIsacfix_ControlBwe(...)
252  *
253  * This function sets the initial values of bottleneck and frame-size if
254  * iSAC is used in channel-adaptive mode. Through this API, users can
255  * enforce a frame-size for all values of bottleneck. Then iSAC will not
256  * automatically change the frame-size.
257  *
258  *
259  * Input:
260  *      - ISAC_main_inst    : ISAC instance.
261  *      - rateBPS           : initial value of bottleneck in bits/second
262  *                            10000 <= rateBPS <= 32000 is accepted
263  *      - frameSizeMs       : number of milliseconds per frame (30 or 60)
264  *      - enforceFrameSize  : 1 to enforce the given frame-size through out
265  *                            the adaptation process, 0 to let iSAC change
266  *                            the frame-size if required.
267  *
268  * Return value             : 0  - ok
269  *                           -1 - Error
270  */
271 
272 int16_t WebRtcIsacfix_ControlBwe(ISACFIX_MainStruct* ISAC_main_inst,
273                                  int16_t rateBPS,
274                                  int frameSizeMs,
275                                  int16_t enforceFrameSize);
276 
277 /****************************************************************************
278  * WebRtcIsacfix_version(...)
279  *
280  * This function returns the version number.
281  *
282  * Output:
283  *      - version      : Pointer to character string
284  *
285  */
286 
287 void WebRtcIsacfix_version(char* version);
288 
289 /****************************************************************************
290  * WebRtcIsacfix_GetErrorCode(...)
291  *
292  * This function can be used to check the error code of an iSAC instance. When
293  * a function returns -1 a error code will be set for that instance. The
294  * function below extract the code of the last error that occured in the
295  * specified instance.
296  *
297  * Input:
298  *  - ISAC_main_inst        : ISAC instance
299  *
300  * Return value             : Error code
301  */
302 
303 int16_t WebRtcIsacfix_GetErrorCode(ISACFIX_MainStruct* ISAC_main_inst);
304 
305 /****************************************************************************
306  * WebRtcIsacfix_GetUplinkBw(...)
307  *
308  * This function return iSAC send bitrate
309  *
310  * Input:
311  *      - ISAC_main_inst    : iSAC instance
312  *
313  * Return value             : <0 Error code
314  *                            else bitrate
315  */
316 
317 int32_t WebRtcIsacfix_GetUplinkBw(ISACFIX_MainStruct* ISAC_main_inst);
318 
319 /****************************************************************************
320  * WebRtcIsacfix_SetMaxPayloadSize(...)
321  *
322  * This function sets a limit for the maximum payload size of iSAC. The same
323  * value is used both for 30 and 60 msec packets.
324  * The absolute max will be valid until next time the function is called.
325  * NOTE! This function may override the function WebRtcIsacfix_SetMaxRate()
326  *
327  * Input:
328  *      - ISAC_main_inst    : iSAC instance
329  *      - maxPayloadBytes   : maximum size of the payload in bytes
330  *                            valid values are between 100 and 400 bytes
331  *
332  *
333  * Return value             : 0 if sucessful
334  *                           -1 if error happens
335  */
336 
337 int16_t WebRtcIsacfix_SetMaxPayloadSize(ISACFIX_MainStruct* ISAC_main_inst,
338                                         int16_t maxPayloadBytes);
339 
340 /****************************************************************************
341  * WebRtcIsacfix_SetMaxRate(...)
342  *
343  * This function sets the maximum rate which the codec may not exceed for a
344  * singel packet. The maximum rate is set in bits per second.
345  * The codec has an absolute maximum rate of 53400 bits per second (200 bytes
346  * per 30 msec).
347  * It is possible to set a maximum rate between 32000 and 53400 bits per second.
348  *
349  * The rate limit is valid until next time the function is called.
350  *
351  * NOTE! Packet size will never go above the value set if calling
352  * WebRtcIsacfix_SetMaxPayloadSize() (default max packet size is 400 bytes).
353  *
354  * Input:
355  *      - ISAC_main_inst    : iSAC instance
356  *      - maxRateInBytes    : maximum rate in bits per second,
357  *                            valid values are 32000 to 53400 bits
358  *
359  * Return value             : 0 if sucessful
360  *                           -1 if error happens
361  */
362 
363 int16_t WebRtcIsacfix_SetMaxRate(ISACFIX_MainStruct* ISAC_main_inst,
364                                  int32_t maxRate);
365 
366 /****************************************************************************
367  * WebRtcIsacfix_CreateInternal(...)
368  *
369  * This function creates the memory that is used to store data in the encoder
370  *
371  * Input:
372  *      - *ISAC_main_inst   : a pointer to the coder instance.
373  *
374  * Return value             : 0 - Ok
375  *                           -1 - Error
376  */
377 
378 int16_t WebRtcIsacfix_CreateInternal(ISACFIX_MainStruct* ISAC_main_inst);
379 
380 /****************************************************************************
381  * WebRtcIsacfix_FreeInternal(...)
382  *
383  * This function frees the internal memory for storing encoder data.
384  *
385  * Input:
386  *      - ISAC_main_inst        : an ISAC instance.
387  *
388  * Return value                 :  0 - Ok
389  *                                -1 - Error
390  */
391 
392 int16_t WebRtcIsacfix_FreeInternal(ISACFIX_MainStruct* ISAC_main_inst);
393 
394 /****************************************************************************
395  * WebRtcIsacfix_GetNewBitStream(...)
396  *
397  * This function returns encoded data, with the recieved bwe-index in the
398  * stream. It should always return a complete packet, i.e. only called once
399  * even for 60 msec frames
400  *
401  * Input:
402  *      - ISAC_main_inst    : ISAC instance.
403  *      - bweIndex          : index of bandwidth estimate to put in new
404  * bitstream - scale             : factor for rate change (0.4 ~=> half the
405  * rate, 1 no change).
406  *
407  * Output:
408  *      - encoded           : the encoded data vector
409  *
410  * Return value             : >0 - Length (in bytes) of coded data
411  *                            -1 - Error
412  */
413 
414 int16_t WebRtcIsacfix_GetNewBitStream(ISACFIX_MainStruct* ISAC_main_inst,
415                                       int16_t bweIndex,
416                                       float scale,
417                                       uint8_t* encoded);
418 
419 /****************************************************************************
420  * WebRtcIsacfix_GetDownLinkBwIndex(...)
421  *
422  * This function returns index representing the Bandwidth estimate from
423  * other side to this side.
424  *
425  * Input:
426  *      - ISAC_main_inst    : iSAC struct
427  *
428  * Output:
429  *      - rateIndex         : Bandwidth estimate to transmit to other side.
430  *
431  */
432 
433 int16_t WebRtcIsacfix_GetDownLinkBwIndex(ISACFIX_MainStruct* ISAC_main_inst,
434                                          int16_t* rateIndex);
435 
436 /****************************************************************************
437  * WebRtcIsacfix_UpdateUplinkBw(...)
438  *
439  * This function takes an index representing the Bandwidth estimate from
440  * this side to other side and updates BWE.
441  *
442  * Input:
443  *      - ISAC_main_inst    : iSAC struct
444  *      - rateIndex         : Bandwidth estimate from other side.
445  *
446  */
447 
448 int16_t WebRtcIsacfix_UpdateUplinkBw(ISACFIX_MainStruct* ISAC_main_inst,
449                                      int16_t rateIndex);
450 
451 /****************************************************************************
452  * WebRtcIsacfix_ReadBwIndex(...)
453  *
454  * This function returns the index of the Bandwidth estimate from the bitstream.
455  *
456  * Input:
457  *      - encoded           : Encoded bitstream
458  *      - encoded_len_bytes : Length of the bitstream in bytes.
459  *
460  * Output:
461  *      - rateIndex         : Bandwidth estimate in bitstream
462  *
463  */
464 
465 int16_t WebRtcIsacfix_ReadBwIndex(const uint8_t* encoded,
466                                   size_t encoded_len_bytes,
467                                   int16_t* rateIndex);
468 
469 /****************************************************************************
470  * WebRtcIsacfix_GetNewFrameLen(...)
471  *
472  * This function return the next frame length (in samples) of iSAC.
473  *
474  * Input:
475  *      -ISAC_main_inst     : iSAC instance
476  *
477  * Return value             : frame lenght in samples
478  */
479 
480 int16_t WebRtcIsacfix_GetNewFrameLen(ISACFIX_MainStruct* ISAC_main_inst);
481 
482 #if defined(__cplusplus)
483 }
484 #endif
485 
486 #endif /* MODULES_AUDIO_CODING_CODECS_ISAC_FIX_INCLUDE_ISACFIX_H_ */
487