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