src/third_party/webrtc/modules/audio_coding/codecs/isac/fix/interface/isacfix.h

   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 "webrtc/typedefs.h"
  18
  19 typedef struct {
  20   void *dummy;
  21 } ISACFIX_MainStruct;
  22
  23
  24 #if defined(__cplusplus)
  25 extern "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   int16_t 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    * Return value
 179    *       :  0 - Ok
 180    *         -1 - Error
 181    */
 182
 183   int16_t WebRtcIsacfix_DecoderInit(ISACFIX_MainStruct *ISAC_main_inst);
 184
 185
 186   /****************************************************************************
 187    * WebRtcIsacfix_UpdateBwEstimate1(...)
 188    *
 189    * This function updates the estimate of the bandwidth.
 190    *
 191    * Input:
 192    *      - ISAC_main_inst    : ISAC instance.
 193    *      - encoded           : encoded ISAC frame(s).
 194    *      - packet_size       : size of the packet.
 195    *      - rtp_seq_number    : the RTP number of the packet.
 196    *      - arr_ts            : the arrival time of the packet (from NetEq)
 197    *                            in samples.
 198    *
 199    * Return value             : 0 - Ok
 200    *                           -1 - Error
 201    */
 202
 203   int16_t WebRtcIsacfix_UpdateBwEstimate1(ISACFIX_MainStruct *ISAC_main_inst,
 204                                           const uint8_t* encoded,
 205                                           int32_t  packet_size,
 206                                           uint16_t rtp_seq_number,
 207                                           uint32_t arr_ts);
 208
 209   /****************************************************************************
 210    * WebRtcIsacfix_UpdateBwEstimate(...)
 211    *
 212    * This function updates the estimate of the bandwidth.
 213    *
 214    * Input:
 215    *      - ISAC_main_inst    : ISAC instance.
 216    *      - encoded           : encoded ISAC frame(s).
 217    *      - packet_size       : size of the packet.
 218    *      - rtp_seq_number    : the RTP number of the packet.
 219    *      - send_ts           : the send time of the packet from RTP header,
 220    *                            in samples.
 221    *      - arr_ts            : the arrival time of the packet (from NetEq)
 222    *                            in samples.
 223    *
 224    * Return value             :  0 - Ok
 225    *                            -1 - Error
 226    */
 227
 228   int16_t WebRtcIsacfix_UpdateBwEstimate(ISACFIX_MainStruct *ISAC_main_inst,
 229                                          const uint8_t* encoded,
 230                                          int32_t          packet_size,
 231                                          uint16_t         rtp_seq_number,
 232                                          uint32_t         send_ts,
 233                                          uint32_t         arr_ts);
 234
 235   /****************************************************************************
 236    * WebRtcIsacfix_Decode(...)
 237    *
 238    * This function decodes an ISAC frame. Output speech length
 239    * will be a multiple of 480 samples: 480 or 960 samples,
 240    * depending on the framesize (30 or 60 ms).
 241    *
 242    * Input:
 243    *      - ISAC_main_inst    : ISAC instance.
 244    *      - encoded           : encoded ISAC frame(s)
 245    *      - len               : bytes in encoded vector
 246    *
 247    * Output:
 248    *      - decoded           : The decoded vector
 249    *
 250    * Return value             : >0 - number of samples in decoded vector
 251    *                            -1 - Error
 252    */
 253
 254   int16_t WebRtcIsacfix_Decode(ISACFIX_MainStruct *ISAC_main_inst,
 255                                const uint8_t* encoded,
 256                                int16_t len,
 257                                int16_t *decoded,
 258                                int16_t *speechType);
 259
 260
 261   /****************************************************************************
 262    * WebRtcIsacfix_DecodeNb(...)
 263    *
 264    * This function decodes a ISAC frame in narrow-band (8 kHz sampling).
 265    * Output speech length will be a multiple of 240 samples: 240 or 480 samples,
 266    * depending on the framesize (30 or 60 ms).
 267    *
 268    * The function is enabled if WEBRTC_ISAC_FIX_NB_CALLS_ENABLED is defined
 269    *
 270    * Input:
 271    *      - ISAC_main_inst    : ISAC instance.
 272    *      - encoded           : encoded ISAC frame(s)
 273    *      - len               : bytes in encoded vector
 274    *
 275    * Output:
 276    *      - decoded           : The decoded vector
 277    *
 278    * Return value             : >0 - number of samples in decoded vector
 279    *                            -1 - Error
 280    */
 281
 282 #ifdef WEBRTC_ISAC_FIX_NB_CALLS_ENABLED
 283   int16_t WebRtcIsacfix_DecodeNb(ISACFIX_MainStruct *ISAC_main_inst,
 284                                  const uint16_t *encoded,
 285                                  int16_t len,
 286                                  int16_t *decoded,
 287                                  int16_t *speechType);
 288 #endif //  WEBRTC_ISAC_FIX_NB_CALLS_ENABLED
 289
 290
 291   /****************************************************************************
 292    * WebRtcIsacfix_DecodePlcNb(...)
 293    *
 294    * This function conducts PLC for ISAC frame(s) in narrow-band (8kHz sampling).
 295    * Output speech length  will be "240*noOfLostFrames" samples
 296    * that equevalent of "30*noOfLostFrames" millisecond.
 297    *
 298    * The function is enabled if WEBRTC_ISAC_FIX_NB_CALLS_ENABLED is defined
 299    *
 300    * Input:
 301    *      - ISAC_main_inst    : ISAC instance.
 302    *      - noOfLostFrames    : Number of PLC frames (240 sample=30ms) to produce
 303    *                            NOTE! Maximum number is 2 (480 samples = 60ms)
 304    *
 305    * Output:
 306    *      - decoded           : The decoded vector
 307    *
 308    * Return value             : >0 - number of samples in decoded PLC vector
 309    *                            -1 - Error
 310    */
 311
 312 #ifdef WEBRTC_ISAC_FIX_NB_CALLS_ENABLED
 313   int16_t WebRtcIsacfix_DecodePlcNb(ISACFIX_MainStruct *ISAC_main_inst,
 314                                     int16_t *decoded,
 315                                     int16_t noOfLostFrames);
 316 #endif // WEBRTC_ISAC_FIX_NB_CALLS_ENABLED
 317
 318
 319
 320
 321   /****************************************************************************
 322    * WebRtcIsacfix_DecodePlc(...)
 323    *
 324    * This function conducts PLC for ISAC frame(s) in wide-band (16kHz sampling).
 325    * Output speech length  will be "480*noOfLostFrames" samples
 326    * that is equevalent of "30*noOfLostFrames" millisecond.
 327    *
 328    * Input:
 329    *      - ISAC_main_inst    : ISAC instance.
 330    *      - noOfLostFrames    : Number of PLC frames (480sample = 30ms)
 331    *                            to produce
 332    *                            NOTE! Maximum number is 2 (960 samples = 60ms)
 333    *
 334    * Output:
 335    *      - decoded           : The decoded vector
 336    *
 337    * Return value             : >0 - number of samples in decoded PLC vector
 338    *                            -1 - Error
 339    */
 340
 341   int16_t WebRtcIsacfix_DecodePlc(ISACFIX_MainStruct *ISAC_main_inst,
 342                                   int16_t *decoded,
 343                                   int16_t noOfLostFrames );
 344
 345
 346   /****************************************************************************
 347    * WebRtcIsacfix_ReadFrameLen(...)
 348    *
 349    * This function returns the length of the frame represented in the packet.
 350    *
 351    * Input:
 352    *      - encoded           : Encoded bitstream
 353    *      - encoded_len_bytes : Length of the bitstream in bytes.
 354    *
 355    * Output:
 356    *      - frameLength       : Length of frame in packet (in samples)
 357    *
 358    */
 359
 360   int16_t WebRtcIsacfix_ReadFrameLen(const uint8_t* encoded,
 361                                      int encoded_len_bytes,
 362                                      int16_t* frameLength);
 363
 364   /****************************************************************************
 365    * WebRtcIsacfix_Control(...)
 366    *
 367    * This function sets the limit on the short-term average bit rate and the
 368    * frame length. Should be used only in Instantaneous mode.
 369    *
 370    * Input:
 371    *      - ISAC_main_inst    : ISAC instance.
 372    *      - rate              : limit on the short-term average bit rate,
 373    *                            in bits/second (between 10000 and 32000)
 374    *      - framesize         : number of milliseconds per frame (30 or 60)
 375    *
 376    * Return value             : 0  - ok
 377    *                           -1 - Error
 378    */
 379
 380   int16_t WebRtcIsacfix_Control(ISACFIX_MainStruct *ISAC_main_inst,
 381                                 int16_t          rate,
 382                                 int16_t          framesize);
 383
 384
 385
 386   /****************************************************************************
 387    * WebRtcIsacfix_ControlBwe(...)
 388    *
 389    * This function sets the initial values of bottleneck and frame-size if
 390    * iSAC is used in channel-adaptive mode. Through this API, users can
 391    * enforce a frame-size for all values of bottleneck. Then iSAC will not
 392    * automatically change the frame-size.
 393    *
 394    *
 395    * Input:
 396    *      - ISAC_main_inst    : ISAC instance.
 397    *      - rateBPS           : initial value of bottleneck in bits/second
 398    *                            10000 <= rateBPS <= 32000 is accepted
 399    *      - frameSizeMs       : number of milliseconds per frame (30 or 60)
 400    *      - enforceFrameSize  : 1 to enforce the given frame-size through out
 401    *                            the adaptation process, 0 to let iSAC change
 402    *                            the frame-size if required.
 403    *
 404    * Return value             : 0  - ok
 405    *                           -1 - Error
 406    */
 407
 408   int16_t WebRtcIsacfix_ControlBwe(ISACFIX_MainStruct *ISAC_main_inst,
 409                                    int16_t rateBPS,
 410                                    int16_t frameSizeMs,
 411                                    int16_t enforceFrameSize);
 412
 413
 414
 415   /****************************************************************************
 416    * WebRtcIsacfix_version(...)
 417    *
 418    * This function returns the version number.
 419    *
 420    * Output:
 421    *      - version      : Pointer to character string
 422    *
 423    */
 424
 425   void WebRtcIsacfix_version(char *version);
 426
 427
 428   /****************************************************************************
 429    * WebRtcIsacfix_GetErrorCode(...)
 430    *
 431    * This function can be used to check the error code of an iSAC instance. When
 432    * a function returns -1 a error code will be set for that instance. The
 433    * function below extract the code of the last error that occured in the
 434    * specified instance.
 435    *
 436    * Input:
 437    *  - ISAC_main_inst        : ISAC instance
 438    *
 439    * Return value             : Error code
 440    */
 441
 442   int16_t WebRtcIsacfix_GetErrorCode(ISACFIX_MainStruct *ISAC_main_inst);
 443
 444
 445   /****************************************************************************
 446    * WebRtcIsacfix_GetUplinkBw(...)
 447    *
 448    * This function return iSAC send bitrate
 449    *
 450    * Input:
 451    *      - ISAC_main_inst    : iSAC instance
 452    *
 453    * Return value             : <0 Error code
 454    *                            else bitrate
 455    */
 456
 457   int32_t WebRtcIsacfix_GetUplinkBw(ISACFIX_MainStruct *ISAC_main_inst);
 458
 459
 460   /****************************************************************************
 461    * WebRtcIsacfix_SetMaxPayloadSize(...)
 462    *
 463    * This function sets a limit for the maximum payload size of iSAC. The same
 464    * value is used both for 30 and 60 msec packets.
 465    * The absolute max will be valid until next time the function is called.
 466    * NOTE! This function may override the function WebRtcIsacfix_SetMaxRate()
 467    *
 468    * Input:
 469    *      - ISAC_main_inst    : iSAC instance
 470    *      - maxPayloadBytes   : maximum size of the payload in bytes
 471    *                            valid values are between 100 and 400 bytes
 472    *
 473    *
 474    * Return value             : 0 if sucessful
 475    *                           -1 if error happens
 476    */
 477
 478   int16_t WebRtcIsacfix_SetMaxPayloadSize(ISACFIX_MainStruct *ISAC_main_inst,
 479                                           int16_t maxPayloadBytes);
 480
 481
 482   /****************************************************************************
 483    * WebRtcIsacfix_SetMaxRate(...)
 484    *
 485    * This function sets the maximum rate which the codec may not exceed for a
 486    * singel packet. The maximum rate is set in bits per second.
 487    * The codec has an absolute maximum rate of 53400 bits per second (200 bytes
 488    * per 30 msec).
 489    * It is possible to set a maximum rate between 32000 and 53400 bits per second.
 490    *
 491    * The rate limit is valid until next time the function is called.
 492    *
 493    * NOTE! Packet size will never go above the value set if calling
 494    * WebRtcIsacfix_SetMaxPayloadSize() (default max packet size is 400 bytes).
 495    *
 496    * Input:
 497    *      - ISAC_main_inst    : iSAC instance
 498    *      - maxRateInBytes    : maximum rate in bits per second,
 499    *                            valid values are 32000 to 53400 bits
 500    *
 501    * Return value             : 0 if sucessful
 502    *                           -1 if error happens
 503    */
 504
 505   int16_t WebRtcIsacfix_SetMaxRate(ISACFIX_MainStruct *ISAC_main_inst,
 506                                    int32_t maxRate);
 507
 508   /****************************************************************************
 509    * WebRtcIsacfix_CreateInternal(...)
 510    *
 511    * This function creates the memory that is used to store data in the encoder
 512    *
 513    * Input:
 514    *      - *ISAC_main_inst   : a pointer to the coder instance.
 515    *
 516    * Return value             : 0 - Ok
 517    *                           -1 - Error
 518    */
 519
 520   int16_t WebRtcIsacfix_CreateInternal(ISACFIX_MainStruct *ISAC_main_inst);
 521
 522
 523   /****************************************************************************
 524    * WebRtcIsacfix_FreeInternal(...)
 525    *
 526    * This function frees the internal memory for storing encoder data.
 527    *
 528    * Input:
 529    *      - ISAC_main_inst        : an ISAC instance.
 530    *
 531    * Return value                 :  0 - Ok
 532    *                                -1 - Error
 533    */
 534
 535   int16_t WebRtcIsacfix_FreeInternal(ISACFIX_MainStruct *ISAC_main_inst);
 536
 537
 538   /****************************************************************************
 539    * WebRtcIsacfix_GetNewBitStream(...)
 540    *
 541    * This function returns encoded data, with the recieved bwe-index in the
 542    * stream. It should always return a complete packet, i.e. only called once
 543    * even for 60 msec frames
 544    *
 545    * Input:
 546    *      - ISAC_main_inst    : ISAC instance.
 547    *      - bweIndex          : index of bandwidth estimate to put in new bitstream
 548    *      - scale             : factor for rate change (0.4 ~=> half the rate, 1 no change).
 549    *
 550    * Output:
 551    *      - encoded           : the encoded data vector
 552    *
 553    * Return value             : >0 - Length (in bytes) of coded data
 554    *                            -1 - Error
 555    */
 556
 557   int16_t WebRtcIsacfix_GetNewBitStream(ISACFIX_MainStruct *ISAC_main_inst,
 558                                         int16_t          bweIndex,
 559                                         float              scale,
 560                                         uint8_t* encoded);
 561
 562
 563   /****************************************************************************
 564    * WebRtcIsacfix_GetDownLinkBwIndex(...)
 565    *
 566    * This function returns index representing the Bandwidth estimate from
 567    * other side to this side.
 568    *
 569    * Input:
 570    *      - ISAC_main_inst    : iSAC struct
 571    *
 572    * Output:
 573    *      - rateIndex         : Bandwidth estimate to transmit to other side.
 574    *
 575    */
 576
 577   int16_t WebRtcIsacfix_GetDownLinkBwIndex(ISACFIX_MainStruct* ISAC_main_inst,
 578                                            int16_t*     rateIndex);
 579
 580
 581   /****************************************************************************
 582    * WebRtcIsacfix_UpdateUplinkBw(...)
 583    *
 584    * This function takes an index representing the Bandwidth estimate from
 585    * this side to other side and updates BWE.
 586    *
 587    * Input:
 588    *      - ISAC_main_inst    : iSAC struct
 589    *      - rateIndex         : Bandwidth estimate from other side.
 590    *
 591    */
 592
 593   int16_t WebRtcIsacfix_UpdateUplinkBw(ISACFIX_MainStruct* ISAC_main_inst,
 594                                        int16_t     rateIndex);
 595
 596
 597   /****************************************************************************
 598    * WebRtcIsacfix_ReadBwIndex(...)
 599    *
 600    * This function returns the index of the Bandwidth estimate from the bitstream.
 601    *
 602    * Input:
 603    *      - encoded           : Encoded bitstream
 604    *      - encoded_len_bytes : Length of the bitstream in bytes.
 605    *
 606    * Output:
 607    *      - rateIndex         : Bandwidth estimate in bitstream
 608    *
 609    */
 610
 611   int16_t WebRtcIsacfix_ReadBwIndex(const uint8_t* encoded,
 612                                     int encoded_len_bytes,
 613                                     int16_t* rateIndex);
 614
 615
 616   /****************************************************************************
 617    * WebRtcIsacfix_GetNewFrameLen(...)
 618    *
 619    * This function return the next frame length (in samples) of iSAC.
 620    *
 621    * Input:
 622    *      -ISAC_main_inst     : iSAC instance
 623    *
 624    * Return value             : frame lenght in samples
 625    */
 626
 627   int16_t WebRtcIsacfix_GetNewFrameLen(ISACFIX_MainStruct *ISAC_main_inst);
 628
 629
 630 #if defined(__cplusplus)
 631 }
 632 #endif
 633
 634
 635
 636 #endif /* WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_FIX_INTERFACE_ISACFIX_H_ */