xref: /external/webrtc/src/modules/audio_coding/codecs/isac/main/interface/isac.h

/*
 *  Copyright (c) 2011 The WebRTC project authors. All Rights Reserved.
 *
 *  Use of this source code is governed by a BSD-style license
 *  that can be found in the LICENSE file in the root of the source
 *  tree. An additional intellectual property rights grant can be found
 *  in the file PATENTS.  All contributing project authors may
 *  be found in the AUTHORS file in the root of the source tree.
 */

#ifndef WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_INTERFACE_ISAC_H_
#define WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_INTERFACE_ISAC_H_

/*
 * Define the fixed-point numeric formats
 */
#include "typedefs.h"

typedef struct WebRtcISACStruct    ISACStruct;

enum IsacSamplingRate {kIsacWideband = 16,  kIsacSuperWideband = 32};


#if defined(__cplusplus)
extern "C" {
#endif

  /******************************************************************************
   * WebRtcIsac_AssignSize(...)
   *
   * This function returns the size of the ISAC instance, so that the instance
   * can be created outside iSAC.
   *
   * Input:
   *        - samplingRate      : sampling rate of the input/output audio.
   *
   * Output:
   *        - sizeinbytes       : number of bytes needed to allocate for the
   *                              instance.
   *
   * Return value               : 0 - Ok
   *                             -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_AssignSize(
      int* sizeinbytes);


  /******************************************************************************
   * WebRtcIsac_Assign(...)
   *
   * This function assignes the memory already created to the ISAC instance.
   *
   * Input:
   *        - *ISAC_main_inst   : a pointer to the coder instance.
   *        - samplingRate      : sampling rate of the input/output audio.
   *        - ISAC_inst_Addr    : the already allocated memory, where we put the
   *                              iSAC structure.
   *
   * Return value               : 0 - Ok
   *                             -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_Assign(
      ISACStruct** ISAC_main_inst,
      void*        ISAC_inst_Addr);


  /******************************************************************************
   * WebRtcIsac_Create(...)
   *
   * This function creates an ISAC instance, which will contain the state
   * information for one coding/decoding channel.
   *
   * Input:
   *        - *ISAC_main_inst   : a pointer to the coder instance.
   *
   * Return value               : 0 - Ok
   *                             -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_Create(
      ISACStruct** ISAC_main_inst);


  /******************************************************************************
   * WebRtcIsac_Free(...)
   *
   * This function frees the ISAC instance created at the beginning.
   *
   * Input:
   *        - ISAC_main_inst    : an ISAC instance.
   *
   * Return value               : 0 - Ok
   *                             -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_Free(
      ISACStruct* ISAC_main_inst);


  /******************************************************************************
   * WebRtcIsac_EncoderInit(...)
   *
   * This function initializes an ISAC instance prior to the encoder calls.
   *
   * Input:
   *        - ISAC_main_inst    : ISAC instance.
   *        - CodingMode        : 0 -> Bit rate and frame length are
   *                                automatically adjusted to available bandwidth
   *                                on transmission channel, just valid if codec
   *                                is created to work in wideband mode.
   *                              1 -> User sets a frame length and a target bit
   *                                rate which is taken as the maximum
   *                                short-term average bit rate.
   *
   * Return value               : 0 - Ok
   *                             -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_EncoderInit(
      ISACStruct* ISAC_main_inst,
      WebRtc_Word16 CodingMode);


  /******************************************************************************
   * WebRtcIsac_Encode(...)
   *
   * This function encodes 10ms audio blocks and inserts it into a package.
   * Input speech length has 160 samples if operating at 16 kHz sampling
   * rate, or 320 if operating at 32 kHz sampling rate. The encoder buffers the
   * input audio until the whole frame is buffered then proceeds with encoding.
   *
   *
   * Input:
   *        - ISAC_main_inst    : ISAC instance.
   *        - speechIn          : input speech vector.
   *
   * Output:
   *        - encoded           : the encoded data vector
   *
   * Return value:
   *                            : >0 - Length (in bytes) of coded data
   *                            :  0 - The buffer didn't reach the chosen
   *                               frame-size so it keeps buffering speech
   *                               samples.
   *                            : -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_Encode(
      ISACStruct*        ISAC_main_inst,
      const WebRtc_Word16* speechIn,
      WebRtc_Word16*       encoded);


  /******************************************************************************
   * WebRtcIsac_DecoderInit(...)
   *
   * This function initializes an ISAC instance prior to the decoder calls.
   *
   * Input:
   *        - ISAC_main_inst    : ISAC instance.
   *
   * Return value
   *                            : 0 - Ok
   *                             -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_DecoderInit(
      ISACStruct* ISAC_main_inst);


  /******************************************************************************
   * WebRtcIsac_UpdateBwEstimate(...)
   *
   * This function updates the estimate of the bandwidth.
   *
   * Input:
   *        - ISAC_main_inst    : ISAC instance.
   *        - encoded           : encoded ISAC frame(s).
   *        - packet_size       : size of the packet.
   *        - rtp_seq_number    : the RTP number of the packet.
   *        - send_ts           : the RTP send timestamp, given in samples
   *        - arr_ts            : the arrival time of the packet (from NetEq)
   *                              in samples.
   *
   * Return value               : 0 - Ok
   *                             -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_UpdateBwEstimate(
      ISACStruct*         ISAC_main_inst,
      const WebRtc_UWord16* encoded,
      WebRtc_Word32         packet_size,
      WebRtc_UWord16        rtp_seq_number,
      WebRtc_UWord32        send_ts,
      WebRtc_UWord32        arr_ts);


  /******************************************************************************
   * WebRtcIsac_Decode(...)
   *
   * This function decodes an ISAC frame. At 16 kHz sampling rate, the length
   * of the output audio could be either 480 or 960 samples, equivalent to
   * 30 or 60 ms respectively. At 32 kHz sampling rate, the length of the
   * output audio is 960 samples, which is 30 ms.
   *
   * Input:
   *        - ISAC_main_inst    : ISAC instance.
   *        - encoded           : encoded ISAC frame(s).
   *        - len               : bytes in encoded vector.
   *
   * Output:
   *        - decoded           : The decoded vector.
   *
   * Return value               : >0 - number of samples in decoded vector.
   *                              -1 - Error.
   */

  WebRtc_Word16 WebRtcIsac_Decode(
      ISACStruct*           ISAC_main_inst,
      const WebRtc_UWord16* encoded,
      WebRtc_Word16         len,
      WebRtc_Word16*        decoded,
      WebRtc_Word16*        speechType);


  /******************************************************************************
   * WebRtcIsac_DecodePlc(...)
   *
   * This function conducts PLC for ISAC frame(s). Output speech length
   * will be a multiple of frames, i.e. multiples of 30 ms audio. Therefore,
   * the output is multiple of 480 samples if operating at 16 kHz and multiple
   * of 960 if operating at 32 kHz.
   *
   * Input:
   *        - ISAC_main_inst    : ISAC instance.
   *        - noOfLostFrames    : Number of PLC frames to produce.
   *
   * Output:
   *        - decoded           : The decoded vector.
   *
   * Return value               : >0 - number of samples in decoded PLC vector
   *                              -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_DecodePlc(
      ISACStruct*  ISAC_main_inst,
      WebRtc_Word16* decoded,
      WebRtc_Word16  noOfLostFrames);


  /******************************************************************************
   * WebRtcIsac_Control(...)
   *
   * This function sets the limit on the short-term average bit-rate and the
   * frame length. Should be used only in Instantaneous mode. At 16 kHz sampling
   * rate, an average bit-rate between 10000 to 32000 bps is valid and a
   * frame-size of 30 or 60 ms is acceptable. At 32 kHz, an average bit-rate
   * between 10000 to 56000 is acceptable, and the valid frame-size is 30 ms.
   *
   * Input:
   *        - ISAC_main_inst    : ISAC instance.
   *        - rate              : limit on the short-term average bit rate,
   *                              in bits/second.
   *        - framesize         : frame-size in millisecond.
   *
   * Return value               : 0  - ok
   *                             -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_Control(
      ISACStruct*   ISAC_main_inst,
      WebRtc_Word32 rate,
      WebRtc_Word16 framesize);


  /******************************************************************************
   * WebRtcIsac_ControlBwe(...)
   *
   * This function sets the initial values of bottleneck and frame-size if
   * iSAC is used in channel-adaptive mode. Therefore, this API is not
   * applicable if the codec is created to operate in super-wideband mode.
   *
   * Through this API, users can enforce a frame-size for all values of
   * bottleneck. Then iSAC will not automatically change the frame-size.
   *
   *
   * Input:
   *        - ISAC_main_inst    : ISAC instance.
   *        - rateBPS           : initial value of bottleneck in bits/second
   *                              10000 <= rateBPS <= 56000 is accepted
   *                              For default bottleneck set rateBPS = 0
   *        - frameSizeMs       : number of milliseconds per frame (30 or 60)
   *        - enforceFrameSize  : 1 to enforce the given frame-size through
   *                              out the adaptation process, 0 to let iSAC
   *                              change the frame-size if required.
   *
   * Return value               : 0  - ok
   *                             -1 - Error
   */

  WebRtc_Word16 WebRtcIsac_ControlBwe(
      ISACStruct* ISAC_main_inst,
      WebRtc_Word32 rateBPS,
      WebRtc_Word16 frameSizeMs,
      WebRtc_Word16 enforceFrameSize);


  /******************************************************************************
   * WebRtcIsac_ReadFrameLen(...)
   *
   * This function returns the length of the frame represented in the packet.
   *
   * Input:
   *        - encoded           : Encoded bit-stream
   *
   * Output:
   *        - frameLength       : Length of frame in packet (in samples)
   *
   */

  WebRtc_Word16 WebRtcIsac_ReadFrameLen(
      ISACStruct*          ISAC_main_inst,
      const WebRtc_Word16* encoded,
      WebRtc_Word16*       frameLength);


  /******************************************************************************
   * WebRtcIsac_version(...)
   *
   * This function returns the version number.
   *
   * Output:
   *        - version      : Pointer to character string
   *
   */

  void WebRtcIsac_version(
      char *version);


  /******************************************************************************
   * WebRtcIsac_GetErrorCode(...)
   *
   * This function can be used to check the error code of an iSAC instance. When
   * a function returns -1 a error code will be set for that instance. The
   * function below extract the code of the last error that occurred in the
   * specified instance.
   *
   * Input:
   *        - ISAC_main_inst    : ISAC instance
   *
   * Return value               : Error code
   */

  WebRtc_Word16 WebRtcIsac_GetErrorCode(
      ISACStruct* ISAC_main_inst);


  /****************************************************************************
   * WebRtcIsac_GetUplinkBw(...)
   *
   * This function outputs the target bottleneck of the codec. In
   * channel-adaptive mode, the target bottleneck is specified through in-band
   * signalling retreived by bandwidth estimator.
   * In channel-independent, also called instantaneous mode, the target
   * bottleneck is provided to the encoder by calling xxx_control(...). If
   * xxx_control is never called the default values is returned. The default
   * value for bottleneck at 16 kHz encoder sampling rate is 32000 bits/sec,
   * and it is 56000 bits/sec for 32 kHz sampling rate.
   * Note that the output is the iSAC internal operating bottleneck which might
   * differ slightly from the one provided through xxx_control().
   *
   * Input:
   *        - ISAC_main_inst    : iSAC instance
   *
   * Output:
   *        - *bottleneck       : bottleneck in bits/sec
   *
   * Return value               : -1 if error happens
   *                               0 bit-rates computed correctly.
   */

  WebRtc_Word16 WebRtcIsac_GetUplinkBw(
      ISACStruct*    ISAC_main_inst,
      WebRtc_Word32* bottleneck);


  /******************************************************************************
   * WebRtcIsac_SetMaxPayloadSize(...)
   *
   * This function sets a limit for the maximum payload size of iSAC. The same
   * value is used both for 30 and 60 ms packets. If the encoder sampling rate
   * is 16 kHz the maximum payload size is between 120 and 400 bytes. If the
   * encoder sampling rate is 32 kHz the maximum payload size is between 120
   * and 600 bytes.
   *
   * If an out of range limit is used, the function returns -1, but the closest
   * valid value will be applied.
   *
   * ---------------
   * IMPORTANT NOTES
   * ---------------
   * The size of a packet is limited to the minimum of 'max-payload-size' and
   * 'max-rate.' For instance, let's assume the max-payload-size is set to
   * 170 bytes, and max-rate is set to 40 kbps. Note that a limit of 40 kbps
   * translates to 150 bytes for 30ms frame-size & 300 bytes for 60ms
   * frame-size. Then a packet with a frame-size of 30 ms is limited to 150,
   * i.e. min(170, 150), and a packet with 60 ms frame-size is limited to
   * 170 bytes, i.e. min(170, 300).
   *
   * Input:
   *        - ISAC_main_inst    : iSAC instance
   *        - maxPayloadBytes   : maximum size of the payload in bytes
   *                              valid values are between 120 and 400 bytes
   *                              if encoder sampling rate is 16 kHz. For
   *                              32 kHz encoder sampling rate valid values
   *                              are between 120 and 600 bytes.
   *
   * Return value               : 0 if successful
   *                             -1 if error happens
   */

  WebRtc_Word16 WebRtcIsac_SetMaxPayloadSize(
      ISACStruct* ISAC_main_inst,
      WebRtc_Word16 maxPayloadBytes);


  /******************************************************************************
   * WebRtcIsac_SetMaxRate(...)
   *
   * This function sets the maximum rate which the codec may not exceed for
   * any signal packet. The maximum rate is defined and payload-size per
   * frame-size in bits per second.
   *
   * The codec has a maximum rate of 53400 bits per second (200 bytes per 30
   * ms) if the encoder sampling rate is 16kHz, and 160 kbps (600 bytes/30 ms)
   * if the encoder sampling rate is 32 kHz.
   *
   * It is possible to set a maximum rate between 32000 and 53400 bits/sec
   * in wideband mode, and 32000 to 160000 bits/sec in super-wideband mode.
   *
   * If an out of range limit is used, the function returns -1, but the closest
   * valid value will be applied.
   *
   * ---------------
   * IMPORTANT NOTES
   * ---------------
   * The size of a packet is limited to the minimum of 'max-payload-size' and
   * 'max-rate.' For instance, let's assume the max-payload-size is set to
   * 170 bytes, and max-rate is set to 40 kbps. Note that a limit of 40 kbps
   * translates to 150 bytes for 30ms frame-size & 300 bytes for 60ms
   * frame-size. Then a packet with a frame-size of 30 ms is limited to 150,
   * i.e. min(170, 150), and a packet with 60 ms frame-size is limited to
   * 170 bytes, min(170, 300).
   *
   * Input:
   *        - ISAC_main_inst    : iSAC instance
   *        - maxRate           : maximum rate in bits per second,
   *                              valid values are 32000 to 53400 bits/sec in
   *                              wideband mode, and 32000 to 160000 bits/sec in
   *                              super-wideband mode.
   *
   * Return value               : 0 if successful
   *                             -1 if error happens
   */

  WebRtc_Word16 WebRtcIsac_SetMaxRate(
      ISACStruct* ISAC_main_inst,
      WebRtc_Word32 maxRate);


  /******************************************************************************
   * WebRtcIsac_DecSampRate()
   * Return the sampling rate of the decoded audio.
   *
   * Input:
   *        - ISAC_main_inst    : iSAC instance
   *
   * Return value               : enumerator representing sampling frequency
   *                              associated with the decoder, i.e. the
   *                              sampling rate of the decoded audio.
   *
   */

  enum IsacSamplingRate WebRtcIsac_DecSampRate(
      ISACStruct*                ISAC_main_inst);


  /******************************************************************************
   * WebRtcIsac_EncSampRate()
   *
   * Input:
   *        - ISAC_main_inst    : iSAC instance
   *
   * Return value               : enumerator representing sampling frequency
   *                              associated with the encoder, the input audio
   *                              is expected to be sampled at this rate.
   *
   */

  enum IsacSamplingRate WebRtcIsac_EncSampRate(
      ISACStruct*                ISAC_main_inst);


  /******************************************************************************
   * WebRtcIsac_SetDecSampRate()
   * Set the sampling rate of the decoder.  Initialization of the decoder WILL
   * NOT overwrite the sampling rate of the encoder. The default value is 16 kHz
   * which is set when the instance is created.
   *
   * Input:
   *        - ISAC_main_inst    : iSAC instance
   *        - sampRate          : enumerator specifying the sampling rate.
   *
   * Return value               : 0 if successful
   *                             -1 if failed.
   */

  WebRtc_Word16 WebRtcIsac_SetDecSampRate(
      ISACStruct*           ISAC_main_inst,
      enum IsacSamplingRate sampRate);


  /******************************************************************************
   * WebRtcIsac_SetEncSampRate()
   * Set the sampling rate of the encoder. Initialization of the encoder WILL
   * NOT overwrite the sampling rate of the encoder. The default value is 16 kHz
   * which is set when the instance is created. The encoding-mode and the
   * bottleneck remain unchanged by this call, however, the maximum rate and
   * maximum payload-size will reset to their default value.
   *
   * Input:
   *        - ISAC_main_inst    : iSAC instance
   *        - sampRate          : enumerator specifying the sampling rate.
   *
   * Return value               : 0 if successful
   *                             -1 if failed.
   */

  WebRtc_Word16 WebRtcIsac_SetEncSampRate(
      ISACStruct*           ISAC_main_inst,
      enum IsacSamplingRate sampRate);



  /******************************************************************************
   * WebRtcIsac_GetNewBitStream(...)
   *
   * This function returns encoded data, with the recieved bwe-index in the
   * stream. If the rate is set to a value less than bottleneck of codec
   * the new bistream will be re-encoded with the given target rate.
   * It should always return a complete packet, i.e. only called once
   * even for 60 msec frames.
   *
   * NOTE 1! This function does not write in the ISACStruct, it is not allowed.
   * NOTE 2! Currently not implemented for SWB mode.
   * NOTE 3! Rates larger than the bottleneck of the codec will be limited
   *         to the current bottleneck.
   *
   * Input:
   *        - ISAC_main_inst    : ISAC instance.
   *        - bweIndex          : Index of bandwidth estimate to put in new
   *                              bitstream
   *        - rate              : target rate of the transcoder is bits/sec.
   *                              Valid values are the accepted rate in iSAC,
   *                              i.e. 10000 to 56000.
   *        - isRCU                       : if the new bit-stream is an RCU stream.
   *                              Note that the rate parameter always indicates
   *                              the target rate of the main paylaod, regardless
   *                              of 'isRCU' value.
   *
   * Output:
   *        - encoded           : The encoded data vector
   *
   * Return value               : >0 - Length (in bytes) of coded data
   *                              -1 - Error  or called in SWB mode
   *                                 NOTE! No error code is written to
   *                                 the struct since it is only allowed to read
   *                                 the struct.
   */
  WebRtc_Word16 WebRtcIsac_GetNewBitStream(
      ISACStruct*    ISAC_main_inst,
      WebRtc_Word16  bweIndex,
      WebRtc_Word16  jitterInfo,
      WebRtc_Word32  rate,
      WebRtc_Word16* encoded,
      WebRtc_Word16  isRCU);



  /****************************************************************************
   * WebRtcIsac_GetDownLinkBwIndex(...)
   *
   * This function returns index representing the Bandwidth estimate from
   * other side to this side.
   *
   * Input:
   *        - ISAC_main_inst    : iSAC struct
   *
   * Output:
   *        - bweIndex          : Bandwidth estimate to transmit to other side.
   *
   */

  WebRtc_Word16 WebRtcIsac_GetDownLinkBwIndex(
      ISACStruct*  ISAC_main_inst,
      WebRtc_Word16* bweIndex,
      WebRtc_Word16* jitterInfo);


  /****************************************************************************
   * WebRtcIsac_UpdateUplinkBw(...)
   *
   * This function takes an index representing the Bandwidth estimate from
   * this side to other side and updates BWE.
   *
   * Input:
   *        - ISAC_main_inst    : iSAC struct
   *        - bweIndex          : Bandwidth estimate from other side.
   *
   */

  WebRtc_Word16 WebRtcIsac_UpdateUplinkBw(
      ISACStruct* ISAC_main_inst,
      WebRtc_Word16 bweIndex);


  /****************************************************************************
   * WebRtcIsac_ReadBwIndex(...)
   *
   * This function returns the index of the Bandwidth estimate from the bitstream.
   *
   * Input:
   *        - encoded           : Encoded bitstream
   *
   * Output:
   *        - frameLength       : Length of frame in packet (in samples)
   *        - bweIndex         : Bandwidth estimate in bitstream
   *
   */

  WebRtc_Word16 WebRtcIsac_ReadBwIndex(
      const WebRtc_Word16* encoded,
      WebRtc_Word16*       bweIndex);



  /*******************************************************************************
   * WebRtcIsac_GetNewFrameLen(...)
   *
   * returns the frame lenght (in samples) of the next packet. In the case of channel-adaptive
   * mode, iSAC decides on its frame lenght based on the estimated bottleneck
   * this allows a user to prepare for the next packet (at the encoder)
   *
   * The primary usage is in CE to make the iSAC works in channel-adaptive mode
   *
   * Input:
   *        - ISAC_main_inst     : iSAC struct
   *
   * Return Value                : frame lenght in samples
   *
   */

  WebRtc_Word16 WebRtcIsac_GetNewFrameLen(
      ISACStruct* ISAC_main_inst);


  /****************************************************************************
   *  WebRtcIsac_GetRedPayload(...)
   *
   *  Populates "encoded" with the redundant payload of the recently encoded
   *  frame. This function has to be called once that WebRtcIsac_Encode(...)
   *  returns a positive value. Regardless of the frame-size this function will
   *  be called only once after encoding is completed.
   *
   * Input:
   *      - ISAC_main_inst    : iSAC struct
   *
   * Output:
   *        - encoded            : the encoded data vector
   *
   *
   * Return value:
   *                              : >0 - Length (in bytes) of coded data
   *                              : -1 - Error
   *
   *
   */
  WebRtc_Word16 WebRtcIsac_GetRedPayload(
      ISACStruct*    ISAC_main_inst,
      WebRtc_Word16* encoded);


  /****************************************************************************
   * WebRtcIsac_DecodeRcu(...)
   *
   * This function decodes a redundant (RCU) iSAC frame. Function is called in
   * NetEq with a stored RCU payload i case of packet loss. Output speech length
   * will be a multiple of 480 samples: 480 or 960 samples,
   * depending on the framesize (30 or 60 ms).
   *
   * Input:
   *      - ISAC_main_inst     : ISAC instance.
   *      - encoded            : encoded ISAC RCU frame(s)
   *      - len                : bytes in encoded vector
   *
   * Output:
   *      - decoded            : The decoded vector
   *
   * Return value              : >0 - number of samples in decoded vector
   *                             -1 - Error
   */
  WebRtc_Word16 WebRtcIsac_DecodeRcu(
      ISACStruct*           ISAC_main_inst,
      const WebRtc_UWord16* encoded,
      WebRtc_Word16         len,
      WebRtc_Word16*        decoded,
      WebRtc_Word16*        speechType);


#if defined(__cplusplus)
}
#endif



#endif /* WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_INTERFACE_ISAC_H_ */