/*
 *  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 AUDIO_CODING_MODULE_H
#define AUDIO_CODING_MODULE_H

#include "module.h"
#include "audio_coding_module_typedefs.h"
#include "module_common_types.h"


namespace webrtc
{

// forward declarations
struct CodecInst;


#define WEBRTC_10MS_PCM_AUDIO 960 // 16 bits super wideband 48 Khz


// Callback class used for sending data ready to be packetized
class AudioPacketizationCallback
{
public:
    virtual ~AudioPacketizationCallback() {}
    
    virtual WebRtc_Word32 SendData(
        FrameType               frameType,
        WebRtc_UWord8           payloadType,
        WebRtc_UWord32          timeStamp,
        const WebRtc_UWord8*          payloadData,
        WebRtc_UWord16          payloadSize,
        const RTPFragmentationHeader* fragmentation) = 0;
};

// Callback class used for inband Dtmf detection
class AudioCodingFeedback
{
public:
    virtual ~AudioCodingFeedback() {}

    virtual WebRtc_Word32 IncomingDtmf(
        const WebRtc_UWord8 digitDtmf,
        const bool          end) = 0;
};

// Callback class used for reporting VAD decision
class ACMVADCallback
{
public:
    virtual ~ACMVADCallback() {}
    virtual WebRtc_Word32 InFrameType(
        WebRtc_Word16 frameType) = 0;
};

// Callback class used for reporting receiver statistics
class ACMVQMonCallback
{
public:
    virtual ~ACMVQMonCallback() {}

    virtual WebRtc_Word32 NetEqStatistics(
        const WebRtc_Word32  id,           // current ACM id
        const WebRtc_UWord16 MIUsValid,    // valid voice duration in ms
        const WebRtc_UWord16 MIUsReplaced, // concealed voice duration in ms
        const WebRtc_UWord8  eventFlags,   // concealed voice flags
        const WebRtc_UWord16 delayMS) = 0; // average delay in ms
};

class AudioCodingModule: public Module
{
protected:
    AudioCodingModule(){}
    virtual ~AudioCodingModule(){}

public:
    ///////////////////////////////////////////////////////////////////////////
    // Creation and destruction of a ACM
    //
    static AudioCodingModule* Create(
        const WebRtc_Word32 id);

    static void Destroy(
        AudioCodingModule* module);

    ///////////////////////////////////////////////////////////////////////////
    //   Utility functions
    //

    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 GetVersion()
    // Returns version of the module and its components.
    //
    // Outputs:
    //   -version            : a buffer that the version string is stored.
    //   -remainBuffBytes    : remaining size of the buffer "version" in
    //                         bytes, excluding terminating-null.
    //   -position           : the first character of the ACM version will
    //                         written to version[position] and so on.
    //
    // Return value:
    //   -1 if failed to write the whole version string,
    //    0 if succeeded.
    //
    static WebRtc_Word32 GetVersion(
        WebRtc_Word8*   version,
        WebRtc_UWord32& remainBuffBytes,
        WebRtc_UWord32& position);


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_UWord8 NumberOfCodecs()
    // Returns number of supported codecs.
    //
    // Return value:
    //   number of supported codecs.
    ///
    static WebRtc_UWord8 NumberOfCodecs();


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 Codec()
    // Get supported codec with list number.
    //
    // Input:
    //   -listId             : list number.
    //
    // Output:
    //   -codec              : a structure where the parameters of the codec,
    //                         given by list number is written to.
    //
    // Return value:
    //   -1 if the list number (listId) is invalid.
    //    0 if succeeded.
    //
    static WebRtc_Word32 Codec(
        const WebRtc_UWord8 listId,
        CodecInst&          codec);


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 Codec()
    // Get supported codec with the given codec name and sampling frequency.
    // If the sampling frequency is -1 then the search will be only based on
    // codec name.
    //
    // Input:
    //   -payloadName        : name of the codec.
    //   -samplingFreqHz     : samling frequency of the codec.
    //
    // Output:
    //   -codec              : a structure where the parameters of the codec,
    //                         given by name is written to.
    //
    // Return value:
    //   -1 if the list number (listId) is invalid.
    //    0 if succeeded.
    //
    static WebRtc_Word32 Codec(
        const WebRtc_Word8* payloadName,
        CodecInst&          codec,
        const WebRtc_Word32 samplingFreqHz = -1);


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 Codec()
    //
    // Returns the list number of the given codec name and sampling frequency.
    // If the sampling frequency is -1 then the search will be only based on
    // codec name.
    //
    // Input:
    //   -payloadName        : name of the codec.
    //   -samplingFreqHz     : samling frequency of the codec.
    //
    // Return value:
    //   if the codec is found, the index of the codec in the list,
    //   -1 if the codec is not found.
    //
    static WebRtc_Word32 Codec(
        const WebRtc_Word8* payloadName,
        const WebRtc_Word32 samplingFreqHz = -1);


    ///////////////////////////////////////////////////////////////////////////
    // bool IsCodecValid()
    // Checks the validity of the parameters of the given codec.
    //
    // Input:
    //   -codec              : the structur which keeps the parameters of the
    //                         codec.
    //
    // Reurn value:
    //   true if the parameters are valid,
    //   false if any parameter is not valid.
    //
    static bool IsCodecValid(const CodecInst& codec);

    ///////////////////////////////////////////////////////////////////////////
    //   Sender
    //
    
    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 InitializeSender()
    // Any encoder-related state of ACM will be initialized to the
    // same state when ACM is created. This will not interrupt or
    // effect decoding functionality of ACM. ACM will lose all the
    // encoding-related settings by calling this function.
    // For instance, a send codec has to be registered again.
    //
    // Return value:
    //   -1 if failed to initialize,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 InitializeSender() = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 ResetEncoder()
    // This API resets the states of encoder. All the encoder settings, such as
    // send-codec or VAD/DTX, will be preserved.
    //
    // Return value:
    //   -1 if failed to initialize,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 ResetEncoder() = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 RegisterSendCodec()
    // Registers a codec, specified by "sendCodec," as sending codec.
    // This API can be called multiple of times to register Codec. The last codec
    // registered overwrites the previous ones.
    // The API can also be used to change payload type for CNG and RED, which are
    // registered by default to default payload types.
    // Note that registering CNG and RED won't overwrite speech codecs.
    // This API can be called to set/change the send payload-type, frame-size
    // or encoding rate (if applicable for the codec).
    //
    // Input:
    //   -sendCodec          : Parameters of the codec to be registered, c.f.
    //                         common_types.h for the definition of
    //                         CodecInst.
    //
    // Return value:
    //   -1 if failed to initialize,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 RegisterSendCodec(
        const CodecInst& sendCodec) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SendCodec()
    // Get parameters for the codec currently registered as send codec.
    //
    // Output:
    //   -currentSendCodec          : parameters of the send codec.
    //
    // Return value:
    //   -1 if failed to get send codec,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 SendCodec(
        CodecInst& currentSendCodec) const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SendFrequency()
    // Get the sampling frequency of the current encoder in Hertz.
    //
    // Return value:
    //   positive; sampling frequency [Hz] of the current encoder.
    //   -1 if an error has happened.
    //
    virtual WebRtc_Word32 SendFrequency() const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 Bitrate()
    // Get encoding bit-rate in bits per second.
    //
    // Return value:
    //   positive; encoding rate in bits/sec,
    //   -1 if an error is happened.
    //
    virtual WebRtc_Word32 SendBitrate() const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SetReceivedEstimatedBandwidth()
    // Set available bandwidth [bits/sec] of the up-link channel.
    // This information is used for traffic shaping, and is currently only
    // supported if iSAC is the send codec.
    //
    // Input:
    //   -bw                 : bandwidth in bits/sec estimated for
    //                         up-link.
    // Return value
    //   -1 if error occurred in setting the bandwidth,
    //    0 bandwidth is set successfully.
    //
    virtual WebRtc_Word32 SetReceivedEstimatedBandwidth(
        const WebRtc_Word32 bw) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 RegisterTransportCallback()
    // Register a transport callback which will be called to deliver
    // the encoded buffers whenever Process() is called and a
    // bit-stream is ready.
    //
    // Input:
    //   -transport          : pointer to the callback class
    //                         transport->SendData() is called whenever
    //                         Process() is called and bit-stream is ready
    //                         to deliver.
    //
    // Return value:
    //   -1 if the transport callback could not be registered
    //    0 if registration is successful.
    //
    virtual WebRtc_Word32 RegisterTransportCallback(
        AudioPacketizationCallback* transport) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 Add10MsData()
    // Add 10MS of raw (PCM) audio data to the encoder. If the sampling
    // frequency of the audio does not match the sampling frequency of the
    // current encoder ACM will resample the audio.
    //
    // Input:
    //   -audioFrame         : the input audio frame, containing raw audio
    //                         sampling frequency etc.,
    //                         c.f. module_common_types.h for definition of
    //                         AudioFrame.
    //
    // Return value:
    //      0   successfully added the frame.
    //     -1   some error occurred and data is not added.
    //   < -1   to add the frame to the buffer n samples had to be
    //          overwritten, -n is the return value in this case.
    //
    virtual WebRtc_Word32 Add10MsData(
        const AudioFrame& audioFrame) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // (FEC) Forward Error Correction 
    //

    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SetFECStatus(const bool enable)
    // configure FEC status i.e. on/off.
    //
    // RFC 2198 describes a solution which has a single payload type which
    // signifies a packet with redundancy. That packet then becomes a container,
    // encapsulating multiple payloads into a single RTP packet.
    // Such a scheme is flexible, since any amount of redundancy may be
    // encapsulated within a single packet.  There is, however, a small overhead
    // since each encapsulated payload must be preceded by a header indicating
    // the type of data enclosed.
    //
    // This means that FEC is actually a RED scheme.
    //
    // Input:
    //   -enableFEC          : if true FEC is enabled, otherwise FEC is
    //                         disabled.
    //
    // Return value:
    //   -1 if failed to set FEC status,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 SetFECStatus(
        const bool enableFEC) = 0;

    ///////////////////////////////////////////////////////////////////////////
    // bool FECStatus()
    // Get FEC status
    //
    // Return value
    //   true if FEC is enabled,
    //   false if FEC is disabled.
    //
    virtual bool FECStatus() const = 0;


    ///////////////////////////////////////////////////////////////////////////
    //   (VAD) Voice Activity Detection
    //

    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SetVAD()
    // If DTX is enabled & the codec does not have internal DTX/VAD
    // WebRtc VAD will be automatically enabled and 'enableVAD' is ignored.
    //
    // If DTX is disabled but VAD is enabled no DTX packets are send,
    // regardless of whether the codec has internal DTX/VAD or not. In this
    // case, WebRtc VAD is running to label frames as active/in-active.
    //
    // Inputs:
    //   -enableDTX          : if true DTX is enabled,
    //                         otherwise DTX is disabled.
    //   -enableVAD          : if true VAD is enabled,
    //                         otherwise VAD is disabled.
    //   -vadMode            : determines the aggressiveness of VAD. A more
    //                         aggressive mode results in more frames labeled
    //                         as in-active, c.f. definition of
    //                         ACMVADMode in audio_coding_module_typedefs.h
    //                         for valid values.
    //
    // Return value:
    //   -1 if failed to set up VAD/DTX,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 SetVAD(
        const bool       enableDTX = true,
        const bool       enableVAD = false,
        const ACMVADMode vadMode = VADNormal) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 VAD()
    // Get VAD status.
    //
    // Outputs:
    //   -dtxEnabled         : is set to true if DTX is enabled, otherwise
    //                         is set to false.
    //   -vadEnabled         : is set to true if VAD is enabled, otherwise
    //                         is set to false.
    //   -vadMode            : is set to the current aggressiveness of VAD.
    //
    // Return value:
    //   -1 if fails to retrieve the setting of DTX/VAD,
    //    0 if succeeeded.
    //
    virtual WebRtc_Word32 VAD(
        bool&       dtxEnabled,
        bool&       vadEnabled,
        ACMVADMode& vadMode) const = 0;

    
    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 ReplaceInternalDTXWithWebRtc()
    // Used to replace codec internal DTX scheme with WebRtc. This is only
    // supported for G729, where this call replaces AnnexB with WebRtc DTX.
    //
    // Input:
    //   -useWebRtcDTX         : if false (default) the codec built-in DTX/VAD
    //                         scheme is used, otherwise the internal DTX is
    //                         replaced with WebRtc DTX/VAD.
    //
    // Return value:
    //   -1 if failed to replace codec internal DTX with WebRtc,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 ReplaceInternalDTXWithWebRtc(
        const bool useWebRtcDTX = false) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 IsInternalDTXReplacedWithWebRtc()
    // Get status if the codec internal DTX (when such exists) is replaced with
    // WebRtc DTX. This is only supported for G729.
    //
    // Output:
    //   -usesWebRtcDTX        : is set to true if the codec internal DTX is
    //                         replaced with WebRtc DTX/VAD, otherwise it is set
    //                         to false.
    //
    // Return value:
    //   -1 if failed to determine if codec internal DTX is replaced with WebRtc,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 IsInternalDTXReplacedWithWebRtc(
        bool& usesWebRtcDTX) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 RegisterVADCallback()
    // Call this method to register a callback function which is called
    // any time that ACM encounters an empty frame. That is a frame which is
    // recognized inactive. Depending on the codec WebRtc VAD or internal codec
    // VAD is employed to identify a frame as active/inactive.
    //
    // Input:
    //   -vadCallback        : pointer to a callback function.
    //
    // Return value:
    //   -1 if failed to register the callback function.
    //    0 if the callback function is registered successfully.
    //
    virtual WebRtc_Word32 RegisterVADCallback(
        ACMVADCallback* vadCallback) = 0;


    ///////////////////////////////////////////////////////////////////////////
    //   Receiver
    //

    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 InitializeReceiver()
    // Any decoder-related state of ACM will be initialized to the
    // same state when ACM is created. This will not interrupt or
    // effect encoding functionality of ACM. ACM would lose all the
    // decoding-related settings by calling this function.
    // For instance, all registered codecs are deleted and have to be
    // registered again.
    //
    // Return value:
    //   -1 if failed to initialize,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 InitializeReceiver() = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 ResetDecoder()
    // This API resets the states of decoders. ACM will not lose any
    // decoder-related settings, such as registered codecs.
    //
    // Return value:
    //   -1 if failed to initialize,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 ResetDecoder() = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 ReceiveFrequency()
    // Get sampling frequency of the last received payload.
    //
    // Return value:
    //   non-negative the sampling frequency in Hertz.
    //   -1 if an error has occurred.
    //
    virtual WebRtc_Word32 ReceiveFrequency() const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 PlayoutFrequency()
    // Get sampling frequency of audio played out.
    //
    // Return value:
    //   the sampling frequency in Hertz.
    //
    virtual WebRtc_Word32 PlayoutFrequency() const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 RegisterReceiveCodec()
    // Register possible decoders, can be called multiple times for
    // codecs, CNG-NB, CNG-WB, CNG-SWB, AVT and RED.
    //
    // Input:
    //   -receiveCodec       : parameters of the codec to be registered, c.f.
    //                         common_types.h for the definition of
    //                         CodecInst.
    //
    // Return value:
    //   -1 if failed to register the codec
    //    0 if the codec registered successfully.
    //
    virtual WebRtc_Word32 RegisterReceiveCodec(
        const CodecInst& receiveCodec) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 UnregisterReceiveCodec()
    // Unregister the codec currently registered with a specific payload type
    // from the list of possible receive codecs.
    //
    // Input:
    //   -payloadType        : The number representing the payload type to
    //                         unregister.
    //
    // Output:
    //   -1 if the unregistration fails.
    //    0 if the given codec is successfully unregistered.
    //
    virtual WebRtc_Word32 UnregisterReceiveCodec(
        const WebRtc_Word16 receiveCodec) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 ReceiveCodec()
    // Get the codec associated with last received payload.
    //
    // Output:
    //   -currRcvCodec       : parameters of the codec associated with the last
    //                         received payload, c.f. common_types.h for
    //                         the definition of CodecInst.
    //
    // Return value:
    //   -1 if failed to retrieve the codec,
    //    0 if the codec is successfully retrieved.
    //
    virtual WebRtc_Word32 ReceiveCodec(
        CodecInst& currRcvCodec) const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 IncomingPacket()
    // Call this function to insert a parsed RTP packet into ACM.
    //
    // Inputs:
    //   -incomingPayload    : received payload.
    //   -payloadLengthByte  : the length of payload in bytes.
    //   -rtpInfo            : the relevant information retrieved from RTP
    //                         header.
    //
    // Return value:
    //   -1 if failed to push in the payload
    //    0 if payload is successfully pushed in.
    //
    virtual WebRtc_Word32 IncomingPacket(
        const WebRtc_Word8*    incomingPayload,
        const WebRtc_Word32    payloadLengthByte,
        const WebRtcRTPHeader& rtpInfo) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 IncomingPayload()
    // Call this API to push incoming payloads when there is no rtp-info.
    // The rtp-info will be created in ACM. One usage for this API is when
    // pre-encoded files are pushed in ACM
    //
    // Inputs:
    //   -incomingPayload    : received payload.
    //   -payloadLenghtByte  : the length, in bytes, of the received payload.
    //   -payloadType        : the payload-type. This specifies which codec has
    //                         to be used to decode the payload.
    //   -timestamp          : send timestamp of the payload. ACM starts with
    //                         a random value and increment it by the
    //                         packet-size, which is given when the codec in
    //                         question is registered by RegisterReceiveCodec().
    //                         Therefore, it is essential to have the timestamp
    //                         if the frame-size differ from the registered
    //                         value or if the incoming payload contains DTX
    //                         packets.
    //
    // Return value:
    //   -1 if failed to push in the payload
    //    0 if payload is successfully pushed in.
    //
    virtual WebRtc_Word32 IncomingPayload(
        const WebRtc_Word8*  incomingPayload,
        const WebRtc_Word32  payloadLengthByte,
        const WebRtc_UWord8  payloadType,
        const WebRtc_UWord32 timestamp = 0) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SetMinimumPlayoutDelay()
    // Set Minimum playout delay, used for lip-sync.
    //
    // Input:
    //   -timeMs             : minimum delay in milliseconds.
    //
    // Return value:
    //   -1 if failed to set the delay,
    //    0 if the minimum delay is set.
    //
    virtual WebRtc_Word32 SetMinimumPlayoutDelay(
        const WebRtc_Word32 timeMs) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 Delay()
    // Get the current playout delay.
    //
    // Output:
    //   - delayInMs         : delay in millisecond
    //
    // Return value:
    //   -1 if failed to get the delay,
    //    0 if succeeded to get the delay.
    //
    virtual WebRtc_Word32 Delay(WebRtc_UWord16& delayMs) const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 RegisterIncomingMessagesCallback()
    // Used by the module to deliver messages to the codec module/application
    // when a Dtmf tone is detected, as well as when it stopped.
    //
    // Inputs:
    //   -inMsgCallback      : pointer to callback function which will be called
    //                         if Dtmf is detected.
    //   -cpt                : enables CPT (Call Progress Tone) detection for the
    //                         specified country. c.f. definition of ACMCountries
    //                         in audio_coding_module_typedefs.h for valid
    //                         entries. The default value disables CPT
    //                         detection.
    //
    // Return value:
    //   -1 if the message callback could not be registered
    //    0 if registration is successful.
    //
    virtual WebRtc_Word32 RegisterIncomingMessagesCallback(
        AudioCodingFeedback* inMsgCallback,
        const ACMCountries   cpt = ACMDisableCountryDetection) = 0;

    
    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SetDtmfPlayoutStatus()
    // Configure Dtmf playout, i.e. whether out-of-band
    // Dtmf tones are played or not.
    //
    // Input:
    //   -enable             : if true to enable playout out-of-band Dtmf tones,
    //                         false to disable.
    //
    // Return value:
    //   -1 if the method fails, e.g. Dtmf playout is not supported.
    //    0 if the status is set successfully.
    //
    virtual WebRtc_Word32 SetDtmfPlayoutStatus(const bool enable) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // bool DtmfPlayoutStatus()
    // Get Dtmf playout status.
    //
    // Return value:
    //   true if out-of-band Dtmf tones are played,
    //   false if playout of Dtmf tones is disabled.
    //
    virtual bool DtmfPlayoutStatus() const = 0;
 

    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SetBackgroundNoiseMode()
    // Sets the mode of the background noise playout in an event of long
    // packetloss burst. For the valid modes see the declaration of
    // ACMBackgroundNoiseMode in audio_coding_module_typedefs.h.
    //
    // Input:
    //   -mode               : the mode for the background noise playout.
    //
    // Return value:
    //   -1 if failed to set the mode.
    //    0 if succeeded in setting the mode.
    //
    virtual WebRtc_Word32 SetBackgroundNoiseMode(
        const ACMBackgroundNoiseMode mode) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 BackgroundNoiseMode()
    // Call this method to get the mode of the background noise playout.
    // Playout of background noise is a result of a long packetloss burst.
    // See ACMBackgroundNoiseMode in audio_coding_module_typedefs.h for
    // possible modes.
    //
    // Output:
    //   -mode             : a reference to ACMBackgroundNoiseMode enumerator.
    //
    // Return value:
    //    0 if the output is a valid mode.
    //   -1 if ACM failed to output a valid mode.
    //
    virtual WebRtc_Word32 BackgroundNoiseMode(
        ACMBackgroundNoiseMode& mode) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 PlayoutTimestamp()
    // The send timestamp of an RTP packet is associated with the decoded
    // audio of the packet in question. This function returns the timestamp of
    // the latest audio obtained by calling PlayoutData10ms().
    //
    // Input:
    //   -timestamp          : a reference to a WebRtc_UWord32 to receive the
    //                         timestamp.
    // Return value:
    //    0 if the output is a correct timestamp.
    //   -1 if failed to output the correct timestamp.
    //
    //
    virtual WebRtc_Word32 PlayoutTimestamp(
        WebRtc_UWord32& timestamp) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 DecoderEstimatedBandwidth()
    // Get the estimate of the Bandwidth, in bits/second, based on the incoming
    // stream. This API is useful in one-way communication scenarios, where
    // the bandwidth information is sent in an out-of-band fashion.
    // Currently only supported if iSAC is registered as a reciever.
    //
    // Return value:
    //   >0 bandwidth in bits/second.
    //   -1 if failed to get a bandwidth estimate.
    //
    virtual WebRtc_Word32 DecoderEstimatedBandwidth() const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SetPlayoutMode()
    // Call this API to set the playout mode. Playout mode could be optimized
    // for i) voice, ii) FAX or iii) streaming. In Voice mode, NetEQ is
    // optimized to deliver highest audio quality while maintaining a minimum
    // delay. In FAX mode, NetEQ is optimized to have few delay changes as
    // possible and maintain a constant delay, perhaps large relative to voice
    // mode, to avoid PLC. In streaming mode, we tolerate a little more delay
    // to acheive better jitter robustness.
    //
    // Input:
    //   -mode               : playout mode. Possible inputs are:
    //                         "voice",
    //                         "fax" and
    //                         "streaming".
    //
    // Return value:
    //   -1 if failed to set the mode,
    //    0 if succeeding.
    //
    virtual WebRtc_Word32 SetPlayoutMode(
        const AudioPlayoutMode mode) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // AudioPlayoutMode PlayoutMode()
    // Get playout mode, i.e. whether it is speech, FAX or streaming. See
    // audio_coding_module_typedefs.h for definition of AudioPlayoutMode.
    //
    // Return value:
    //   voice:       is for voice output,
    //   fax:         a mode that is optimized for receiving FAX signals.
    //                In this mode NetEq tries to maintain a constant high
    //                delay to avoid PLC if possible.
    //   streaming:   a mode that is suitable for streaminq. In this mode we
    //                accept longer delay to improve jitter robustness.
    //
    virtual AudioPlayoutMode PlayoutMode() const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 PlayoutData10Ms(
    // Get 10 milliseconds of raw audio data for playout, at the given sampling
    // frequency. ACM will perform a resampling if required.
    //
    // Input:
    //   -desiredFreqHz      : the desired sampling frequency, in Hertz, of the
    //                         output audio. If set to -1, the function returns the
    //                         audio at the current sampling frequency.
    //
    // Output:
    //   -audioFrame         : output audio frame which contains raw audio data
    //                         and other relevant parameters, c.f.
    //                         module_common_types.h for the definition of
    //                         AudioFrame.
    //
    // Return value:
    //   -1 if the function fails,
    //    0 if the function succeeds.
    //
    virtual WebRtc_Word32 PlayoutData10Ms(
        const WebRtc_Word32 desiredFreqHz,
        AudioFrame          &audioFrame) = 0;


    ///////////////////////////////////////////////////////////////////////////
    //   (CNG) Comfort Noise Generation
    //   Generate comfort noise when receiving DTX packets
    //

    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word16 SetReceiveVADStatus()
    // configure VAD status i.e. on/off on the incoming stream
    // Running VAD on decoded audio is desired in some applications, e.g.
    // conferencing.
    //
    // Input:
    //   -enable             : true to enable VAD on incoming stream, and false
    //                         to disable.
    //
    // Return value:
    //   -1 if failed to enable/disable VAD,
    //    0 if succeded to enable/disable VAD.
    //
    virtual WebRtc_Word16 SetReceiveVADStatus(
        const bool enable)  = 0;


    ///////////////////////////////////////////////////////////////////////////
    // bool ReceiveVADStatus()
    // Call this API to get whether VAD is enabled on incoming stream or not.
    // Running VAD on decoded audio is desired in some applications, e.g.
    // conferencing.
    //
    // Return value:
    //   true if VAD is enabled on the incoming stream,
    //   false if VAD is disabled on the incoming stream.
    //
    virtual bool ReceiveVADStatus() const  = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word16 SetReceiveVADMode()
    // Configure VAD aggressiveness on the incoming stream.
    //
    // Input:
    //   -mode               : aggressiveness of the VAD on incoming stream.
    //                         See audio_coding_module_typedefs.h for the
    //                         definition of ACMVADMode, and possible
    //                         values for aggressiveness.
    //
    // Return value:
    //   -1 if fails to set the mode,
    //    0 if the mode is set successfully.
    //
    virtual WebRtc_Word16 SetReceiveVADMode(
        const ACMVADMode mode) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // ACMVADMode ReceiveVADMode()
    // Get VAD aggressiveness on the incoming stream.
    //
    // Return value:
    //   aggressiveness of VAD, running on the incoming stream. A more
    //   aggressive mode means more audio frames will be labeled as in-active.
    //   See audio_coding_module_typedefs.h for the definition of
    //   ACMVADMode.
    //
    virtual ACMVADMode ReceiveVADMode() const = 0;

    ///////////////////////////////////////////////////////////////////////////
    //   Codec specific
    //

    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SetISACMaxRate()
    // Set the maximum instantaneous rate of iSAC. For a payload of B bits
    // with a frame-size of T sec the instantaneous rate is B/T bist per
    // second. Therefore, (B/T < maxRateBitPerSec) and
    // (B < maxPayloadLenBytes * 8) are always satisfied for iSAC payloads,
    // c.f SetISACMaxPayloadSize().
    //
    // Input:
    //   -maxRateBitPerSec   : maximum instantaneous bit-rate given in bits/sec.
    //
    // Return value:
    //   -1 if failed to set the maximum rate.
    //    0 if the maximum rate is set successfully.
    //
    virtual WebRtc_Word32 SetISACMaxRate(
        const WebRtc_UWord32 maxRateBitPerSec) = 0;

    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 SetISACMaxPayloadSize()
    // Set the maximum payload size of iSAC packets. No iSAC payload,
    // regardless of its frame-size, may exceed the given limit. For
    // an iSAC payload of size B bits and frame-size T sec we have;
    // (B < maxPayloadLenBytes * 8) and (B/T < maxRateBitPerSec), c.f.
    // SetISACMaxRate().
    //
    // Input:
    //   -maxPayloadLenBytes : maximum payload size in bytes.
    //
    // Return value:
    //   -1 if failed to set the maximm  payload-size.
    //    0 if the given linit is seet successfully.
    //
    virtual WebRtc_Word32 SetISACMaxPayloadSize(
        const WebRtc_UWord16 maxPayloadLenBytes) = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 ConfigISACBandwidthEstimator()
    // Call this function to configure the bandwidth estimator of ISAC.
    // During the adaptation of bit-rate, iSAC atomatically adjusts the
    // frame-size (either 30 or 60 ms) to save on RTP header. The initial
    // frame-size can be specified by the first argument. The configuration also
    // regards the initial estimate of bandwidths. The estimator starts from
    // this point and converges to the actual bottleneck. This is given by the
    // second parameter. Furthermore, it is also possible to control the
    // adaptation of frame-size. This is specified by the last parameter.
    //
    // Input:
    //   -initFrameSizeMsec  : initial frame-size in milisecods. For iSAC-wb
    //                         30 ms and 60 ms (default) are acceptable values,
    //                         and for iSAC-swb 30 ms is the only acceptable
    //                         value. Zero indiates default value.
    //   -initRateBitPerSec  : initial estimate of the bandwidth. Values
    //                         between 10000 and 58000 are acceptable.
    //   -enforceFrameSize   : if true, the frame-size will not be adapted.
    //
    // Return value:
    //   -1 if failed to configure the bandwidth estimator,
    //    0 if the configuration was successfully applied.
    //
    virtual WebRtc_Word32 ConfigISACBandwidthEstimator(
        const WebRtc_UWord8  initFrameSizeMsec,
        const WebRtc_UWord16 initRateBitPerSec,
        const bool           enforceFrameSize = false) = 0;


    ///////////////////////////////////////////////////////////////////////////
    //   statistics
    //

    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32  NetworkStatistics()
    // Get network statistics.
    //
    // Input:
    //   -networkStatistics  : a structure that contains network statistics.
    //
    // Return value:
    //   -1 if failed to set the network statistics,
    //    0 if statistics are set successfully.
    //
    virtual WebRtc_Word32  NetworkStatistics(
        ACMNetworkStatistics& networkStatistics) const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32  JitterStatistics()
    // Get the jitter statistics.
    //
    // Input:
    //   -jitterStatistics   : the given jitter statistics.
    //
    // Return value:
    //   -1 if failed to set the jitter statistics,
    //    0 if jitter statistics are set successfully.
    //
    virtual WebRtc_Word32  JitterStatistics(
        ACMJitterStatistics& jitterStatistics) const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32  PreferredBufferSize()
    // Get the optimal buffer size calculated for the current network
    // conditions.
    //
    // Output:
    //   -prefBuffSize       : the optimal size of the jitter buffer in
    //                         milliseconds.
    //
    // Return value:
    //   -1 if the preferred buffer size could not be computed,
    //    0 if a valid buffer is computed successfully.
    //
    virtual WebRtc_Word32 PreferredBufferSize(
        WebRtc_UWord16& prefBufSize) const = 0;


    ///////////////////////////////////////////////////////////////////////////
    // WebRtc_Word32 ResetJitterStatistics()
    // Reset jitter statistics.
    //
    // Return value:
    //   -1 if failed to reset the statistics,
    //    0 if succeeded.
    //
    virtual WebRtc_Word32 ResetJitterStatistics() const = 0;
};

} // namespace webrtc

#endif