Note: We no longer publish the latest version of our code here. We primarily use a kumc-bmi github organization. The heron ETL repository, in particular, is not public. Peers in the informatics community should see MultiSiteDev for details on requesting access.

source: webrtc/webrtc/modules/audio_coding/codecs/isac/fix/interface/isacfix.h @ 0:4bda6873e34c

pub_scrub_3792 tip
Last change on this file since 0:4bda6873e34c was 0:4bda6873e34c, checked in by Michael Prittie <mprittie@…>, 6 years ago

Scrubbed password for publication.

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