| /* |
| * Copyright (c) 2012 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_MAIN_SOURCE_ACM_GENERIC_CODEC_H_ |
| #define WEBRTC_MODULES_AUDIO_CODING_MAIN_SOURCE_ACM_GENERIC_CODEC_H_ |
| |
| #include "webrtc/modules/audio_coding/main/interface/audio_coding_module_typedefs.h" |
| #include "webrtc/modules/audio_coding/main/source/acm_common_defs.h" |
| #include "webrtc/modules/audio_coding/neteq/interface/webrtc_neteq.h" |
| #include "webrtc/system_wrappers/interface/rw_lock_wrapper.h" |
| #include "webrtc/system_wrappers/interface/trace.h" |
| |
| #define MAX_FRAME_SIZE_10MSEC 6 |
| |
| // forward declaration |
| struct WebRtcVadInst; |
| struct WebRtcCngEncInst; |
| |
| namespace webrtc { |
| |
| // forward declaration |
| struct CodecInst; |
| |
| namespace acm1 { |
| |
| class ACMNetEQ; |
| |
| class ACMGenericCodec { |
| public: |
| /////////////////////////////////////////////////////////////////////////// |
| // Constructor of the class |
| // |
| ACMGenericCodec(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // Destructor of the class. |
| // |
| virtual ~ACMGenericCodec(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // ACMGenericCodec* CreateInstance(); |
| // The function will be used for FEC. It is not implemented yet. |
| // |
| virtual ACMGenericCodec* CreateInstance() = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t Encode() |
| // The function is called to perform an encoding of the audio stored in |
| // audio buffer. An encoding is performed only if enough audio, i.e. equal |
| // to the frame-size of the codec, exist. The audio frame will be processed |
| // by VAD and CN/DTX if required. There are few different cases. |
| // |
| // A) Neither VAD nor DTX is active; the frame is encoded by the encoder. |
| // |
| // B) VAD is enabled but not DTX; in this case the audio is processed by VAD |
| // and encoded by the encoder. The "*encoding_type" will be either |
| // "kActiveNormalEncode" or "kPassiveNormalEncode" if frame is active or |
| // passive, respectively. |
| // |
| // C) DTX is enabled; if the codec has internal VAD/DTX we just encode the |
| // frame by the encoder. Otherwise, the frame is passed through VAD and |
| // if identified as passive, then it will be processed by CN/DTX. If the |
| // frame is active it will be encoded by the encoder. |
| // |
| // This function acquires the appropriate locks and calls EncodeSafe() for |
| // the actual processing. |
| // |
| // Outputs: |
| // -bitstream : a buffer where bit-stream will be written to. |
| // -bitstream_len_byte : contains the length of the bit-stream in |
| // bytes. |
| // -timestamp : contains the RTP timestamp, this is the |
| // sampling time of the first sample encoded |
| // (measured in number of samples). |
| // -encoding_type : contains the type of encoding applied on the |
| // audio samples. The alternatives are |
| // (c.f. acm_common_types.h) |
| // -kNoEncoding: |
| // there was not enough data to encode. or |
| // some error has happened that we could |
| // not do encoding. |
| // -kActiveNormalEncoded: |
| // the audio frame is active and encoded by |
| // the given codec. |
| // -kPassiveNormalEncoded: |
| // the audio frame is passive but coded with |
| // the given codec (NO DTX). |
| // -kPassiveDTXWB: |
| // The audio frame is passive and used |
| // wide-band CN to encode. |
| // -kPassiveDTXNB: |
| // The audio frame is passive and used |
| // narrow-band CN to encode. |
| // |
| // Return value: |
| // -1 if error is occurred, otherwise the length of the bit-stream in |
| // bytes. |
| // |
| int16_t Encode(uint8_t* bitstream, |
| int16_t* bitstream_len_byte, |
| uint32_t* timestamp, |
| WebRtcACMEncodingType* encoding_type); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t Decode() |
| // This function is used to decode a given bit-stream, without engaging |
| // NetEQ. |
| // |
| // This function acquires the appropriate locks and calls DecodeSafe() for |
| // the actual processing. Please note that this is not functional yet. |
| // |
| // Inputs: |
| // -bitstream : a buffer where bit-stream will be read. |
| // -bitstream_len_byte : the length of the bit-stream in bytes. |
| // |
| // Outputs: |
| // -audio : pointer to a buffer where the audio will written. |
| // -audio_samples : number of audio samples out of decoding the given |
| // bit-stream. |
| // -speech_type : speech type (for future use). |
| // |
| // Return value: |
| // -1 if failed to decode, |
| // 0 if succeeded. |
| // |
| int16_t Decode(uint8_t* bitstream, |
| int16_t bitstream_len_byte, |
| int16_t* audio, |
| int16_t* audio_samples, |
| int8_t* speech_type); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // void SplitStereoPacket() |
| // This function is used to split stereo payloads in left and right channel. |
| // Codecs which has stereo support has there own implementation of the |
| // function. |
| // |
| // Input/Output: |
| // -payload : a vector with the received payload data. |
| // The function will reorder the data so that |
| // first half holds the left channel data, and the |
| // second half the right channel data. |
| // -payload_length : length of payload in bytes. Will be changed to |
| // twice the input in case of true stereo, where |
| // we simply copy the data and return it both for |
| // left channel and right channel decoding. |
| // |
| virtual void SplitStereoPacket(uint8_t* /* payload */, |
| int32_t* /* payload_length */) {} |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // bool EncoderInitialized(); |
| // |
| // Return value: |
| // True if the encoder is successfully initialized, |
| // false otherwise. |
| // |
| bool EncoderInitialized(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // bool DecoderInitialized(); |
| // |
| // Return value: |
| // True if the decoder is successfully initialized, |
| // false otherwise. |
| // |
| bool DecoderInitialized(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t EncoderParams() |
| // It is called to get encoder parameters. It will call |
| // EncoderParamsSafe() in turn. |
| // |
| // Output: |
| // -enc_params : a buffer where the encoder parameters is |
| // written to. If the encoder is not |
| // initialized this buffer is filled with |
| // invalid values |
| // Return value: |
| // -1 if the encoder is not initialized, |
| // 0 otherwise. |
| // |
| int16_t EncoderParams(WebRtcACMCodecParams *enc_params); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t DecoderParams(...) |
| // It is called to get decoder parameters. It will call DecoderParamsSafe() |
| // in turn. |
| // |
| // Output: |
| // -dec_params : a buffer where the decoder parameters is |
| // written to. If the decoder is not initialized |
| // this buffer is filled with invalid values |
| // |
| // Return value: |
| // -1 if the decoder is not initialized, |
| // 0 otherwise. |
| // |
| // |
| bool DecoderParams(WebRtcACMCodecParams *dec_params, |
| const uint8_t payload_type); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t InitEncoder(...) |
| // This function is called to initialize the encoder with the given |
| // parameters. |
| // |
| // Input: |
| // -codec_params : parameters of encoder. |
| // -force_initialization: if false the initialization is invoked only if |
| // the encoder is not initialized. If true the |
| // encoder is forced to (re)initialize. |
| // |
| // Return value: |
| // 0 if could initialize successfully, |
| // -1 if failed to initialize. |
| // |
| // |
| int16_t InitEncoder(WebRtcACMCodecParams* codec_params, |
| bool force_initialization); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t InitDecoder() |
| // This function is called to initialize the decoder with the given |
| // parameters. (c.f. acm_common_defs.h & common_types.h for the |
| // definition of the structure) |
| // |
| // Input: |
| // -codec_params : parameters of decoder. |
| // -force_initialization: if false the initialization is invoked only |
| // if the decoder is not initialized. If true |
| // the encoder is forced to(re)initialize. |
| // |
| // Return value: |
| // 0 if could initialize successfully, |
| // -1 if failed to initialize. |
| // |
| // |
| int16_t InitDecoder(WebRtcACMCodecParams* codec_params, |
| bool force_initialization); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int32_t RegisterInNetEq(...) |
| // This function is called to register the decoder in NetEq, with the given |
| // payload type. |
| // |
| // Inputs: |
| // -neteq : pointer to NetEq Instance |
| // -codec_inst : instance with of the codec settings of the codec |
| // |
| // Return values |
| // -1 if failed to register, |
| // 0 if successfully initialized. |
| // |
| int32_t RegisterInNetEq(ACMNetEQ* neteq, const CodecInst& codec_inst); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int32_t Add10MsData(...) |
| // This function is called to add 10 ms of audio to the audio buffer of |
| // the codec. |
| // |
| // Inputs: |
| // -timestamp : the timestamp of the 10 ms audio. the timestamp |
| // is the sampling time of the |
| // first sample measured in number of samples. |
| // -data : a buffer that contains the audio. The codec |
| // expects to get the audio in correct sampling |
| // frequency |
| // -length : the length of the audio buffer |
| // -audio_channel : 0 for mono, 1 for stereo (not supported yet) |
| // |
| // Return values: |
| // -1 if failed |
| // 0 otherwise. |
| // |
| int32_t Add10MsData(const uint32_t timestamp, |
| const int16_t* data, |
| const uint16_t length, |
| const uint8_t audio_channel); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // uint32_t NoMissedSamples() |
| // This function returns the number of samples which are overwritten in |
| // the audio buffer. The audio samples are overwritten if the input audio |
| // buffer is full, but Add10MsData() is called. (We might remove this |
| // function if it is not used) |
| // |
| // Return Value: |
| // Number of samples which are overwritten. |
| // |
| uint32_t NoMissedSamples() const; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // void ResetNoMissedSamples() |
| // This function resets the number of overwritten samples to zero. |
| // (We might remove this function if we remove NoMissedSamples()) |
| // |
| void ResetNoMissedSamples(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t SetBitRate() |
| // The function is called to set the encoding rate. |
| // |
| // Input: |
| // -bitrate_bps : encoding rate in bits per second |
| // |
| // Return value: |
| // -1 if failed to set the rate, due to invalid input or given |
| // codec is not rate-adjustable. |
| // 0 if the rate is adjusted successfully |
| // |
| int16_t SetBitRate(const int32_t bitrate_bps); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // DestructEncoderInst() |
| // This API is used in conferencing. It will free the memory that is pointed |
| // by |ptr_inst|. |ptr_inst| is a pointer to encoder instance, created and |
| // filled up by calling EncoderInst(...). |
| // |
| // Inputs: |
| // -ptr_inst : pointer to an encoder instance to be deleted. |
| // |
| // |
| void DestructEncoderInst(void* ptr_inst); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t AudioBuffer() |
| // This is used when synchronization of codecs is required. There are cases |
| // that the audio buffers of two codecs have to be synched. By calling this |
| // function on can get the audio buffer and other related parameters, such |
| // as timestamps... |
| // |
| // Output: |
| // -audio_buff : a pointer to WebRtcACMAudioBuff where the audio |
| // buffer of this codec will be written to. |
| // |
| // Return value: |
| // -1 if fails to copy the audio buffer, |
| // 0 if succeeded. |
| // |
| int16_t AudioBuffer(WebRtcACMAudioBuff& audio_buff); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // uint32_t EarliestTimestamp() |
| // Returns the timestamp of the first 10 ms in audio buffer. This is used |
| // to identify if a synchronization of two encoders is required. |
| // |
| // Return value: |
| // timestamp of the first 10 ms audio in the audio buffer. |
| // |
| uint32_t EarliestTimestamp() const; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t SetAudioBuffer() |
| // This function is called to set the audio buffer and the associated |
| // parameters to a given value. |
| // |
| // Return value: |
| // -1 if fails to copy the audio buffer, |
| // 0 if succeeded. |
| // |
| int16_t SetAudioBuffer(WebRtcACMAudioBuff& audio_buff); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t SetVAD() |
| // This is called to set VAD & DTX. If the codec has internal DTX, it will |
| // be used. If DTX is enabled and the codec does not have internal DTX, |
| // WebRtc-VAD will be used to decide if the frame is active. If DTX is |
| // disabled but VAD is enabled the audio is passed through VAD to label it |
| // as active or passive, but the frame is encoded normally. However the |
| // bit-stream is labeled properly so that ACM::Process() can use this |
| // information. In case of failure, the previous states of the VAD & DTX |
| // are kept. |
| // |
| // Input/Output: |
| // -enable_dtx : if true DTX will be enabled otherwise the DTX is |
| // disabled. If codec has internal DTX that will be |
| // used, otherwise WebRtc-CNG is used. In the latter |
| // case VAD is automatically activated. |
| // -enable_vad : if true WebRtc-VAD is enabled, otherwise VAD is |
| // disabled, except for the case that DTX is enabled |
| // but codec doesn't have internal DTX. In this case |
| // VAD is enabled regardless of the value of |
| // |enable_vad|. |
| // -mode : this specifies the aggressiveness of VAD. |
| // |
| // Return value |
| // -1 if failed to set DTX & VAD as specified, |
| // 0 if succeeded. |
| // |
| int16_t SetVAD(bool* enable_dtx, |
| bool* enable_vad, |
| ACMVADMode* mode); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int32_t ReplaceInternalDTX() |
| // This is called to replace the codec internal DTX with WebRtc DTX. |
| // This is only valid for G729 where the user has possibility to replace |
| // AnnexB with WebRtc DTX. For other codecs this function has no effect. |
| // |
| // Input: |
| // -replace_internal_dtx : if true the internal DTX is replaced with WebRtc. |
| // |
| // Return value |
| // -1 if failed to replace internal DTX, |
| // 0 if succeeded. |
| // |
| int32_t ReplaceInternalDTX(const bool replace_internal_dtx); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int32_t IsInternalDTXReplaced() |
| // This is called to check if the codec internal DTX is replaced by WebRtc |
| // DTX. This is only valid for G729 where the user has possibility to replace |
| // AnnexB with WebRtc DTX. For other codecs this function has no effect. |
| // |
| // Output: |
| // -internal_dtx_replaced: if true the internal DTX is replaced with WebRtc. |
| // |
| // Return value |
| // -1 if failed to check |
| // 0 if succeeded. |
| // |
| int32_t IsInternalDTXReplaced(bool* internal_dtx_replaced); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // void SetNetEqDecodeLock() |
| // Passes the NetEq lock to the codec. |
| // |
| // Input: |
| // -neteq_decode_lock : pointer to the lock associated with NetEQ of ACM. |
| // |
| void SetNetEqDecodeLock(RWLockWrapper* neteq_decode_lock) { |
| neteq_decode_lock_ = neteq_decode_lock; |
| } |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // bool HasInternalDTX() |
| // Used to check if the codec has internal DTX. |
| // |
| // Return value: |
| // true if the codec has an internal DTX, e.g. G729, |
| // false otherwise. |
| // |
| bool HasInternalDTX() const { |
| return has_internal_dtx_; |
| } |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int32_t GetEstimatedBandwidth() |
| // Used to get decoder estimated bandwidth. Only iSAC will provide a value. |
| // |
| // |
| // Return value: |
| // -1 if fails to get decoder estimated bandwidth, |
| // >0 estimated bandwidth in bits/sec. |
| // |
| int32_t GetEstimatedBandwidth(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int32_t SetEstimatedBandwidth() |
| // Used to set estiamted bandwidth sent out of band from other side. Only |
| // iSAC will have use for the value. |
| // |
| // Input: |
| // -estimated_bandwidth: estimated bandwidth in bits/sec |
| // |
| // Return value: |
| // -1 if fails to set estimated bandwidth, |
| // 0 on success. |
| // |
| int32_t SetEstimatedBandwidth(int32_t estimated_bandwidth); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int32_t GetRedPayload() |
| // Used to get codec specific RED payload (if such is implemented). |
| // Currently only done in iSAC. |
| // |
| // Outputs: |
| // -red_payload : a pointer to the data for RED payload. |
| // -payload_bytes : number of bytes in RED payload. |
| // |
| // Return value: |
| // -1 if fails to get codec specific RED, |
| // 0 if succeeded. |
| // |
| int32_t GetRedPayload(uint8_t* red_payload, |
| int16_t* payload_bytes); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t ResetEncoder() |
| // By calling this function you would re-initialize the encoder with the |
| // current parameters. All the settings, e.g. VAD/DTX, frame-size... should |
| // remain unchanged. (In case of iSAC we don't want to lose BWE history.) |
| // |
| // Return value |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| int16_t ResetEncoder(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t ResetEncoder() |
| // By calling this function you would re-initialize the decoder with the |
| // current parameters. |
| // |
| // Return value |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| int16_t ResetDecoder(int16_t payload_type); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // void DestructEncoder() |
| // This function is called to delete the encoder instance, if possible, to |
| // have a fresh start. For codecs where encoder and decoder share the same |
| // instance we cannot delete the encoder and instead we will initialize the |
| // encoder. We also delete VAD and DTX if they have been created. |
| // |
| void DestructEncoder(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // void DestructDecoder() |
| // This function is called to delete the decoder instance, if possible, to |
| // have a fresh start. For codecs where encoder and decoder share the same |
| // instance we cannot delete the encoder and instead we will initialize the |
| // decoder. Before deleting decoder instance it has to be removed from the |
| // NetEq list. |
| // |
| void DestructDecoder(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t SamplesLeftToEncode() |
| // Returns the number of samples required to be able to do encoding. |
| // |
| // Return value: |
| // Number of samples. |
| // |
| int16_t SamplesLeftToEncode(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // uint32_t LastEncodedTimestamp() |
| // Returns the timestamp of the last frame it encoded. |
| // |
| // Return value: |
| // Timestamp. |
| // |
| uint32_t LastEncodedTimestamp() const; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // SetUniqueID() |
| // Set a unique ID for the codec to be used for tracing and debugging |
| // |
| // Input |
| // -id : A number to identify the codec. |
| // |
| void SetUniqueID(const uint32_t id); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // IsAudioBufferFresh() |
| // Specifies if ever audio is injected to this codec. |
| // |
| // Return value |
| // -true; no audio is feed into this codec |
| // -false; audio has already been fed to the codec. |
| // |
| bool IsAudioBufferFresh() const; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // UpdateDecoderSampFreq() |
| // For most of the codecs this function does nothing. It must be |
| // implemented for those codecs that one codec instance serves as the |
| // decoder for different flavors of the codec. One example is iSAC. there, |
| // iSAC 16 kHz and iSAC 32 kHz are treated as two different codecs with |
| // different payload types, however, there is only one iSAC instance to |
| // decode. The reason for that is we would like to decode and encode with |
| // the same codec instance for bandwidth estimator to work. |
| // |
| // Each time that we receive a new payload type, we call this function to |
| // prepare the decoder associated with the new payload. Normally, decoders |
| // doesn't have to do anything. For iSAC the decoder has to change it's |
| // sampling rate. The input parameter specifies the current flavor of the |
| // codec in codec database. For instance, if we just got a SWB payload then |
| // the input parameter is ACMCodecDB::isacswb. |
| // |
| // Input: |
| // -codec_id : the ID of the codec associated with the |
| // payload type that we just received. |
| // |
| // Return value: |
| // 0 if succeeded in updating the decoder. |
| // -1 if failed to update. |
| // |
| virtual int16_t UpdateDecoderSampFreq(int16_t /* codec_id */); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // UpdateEncoderSampFreq() |
| // Call this function to update the encoder sampling frequency. This |
| // is for codecs where one payload-name supports several encoder sampling |
| // frequencies. Otherwise, to change the sampling frequency we need to |
| // register new codec. ACM will consider that as registration of a new |
| // codec, not a change in parameter. For iSAC, switching from WB to SWB |
| // is treated as a change in parameter. Therefore, we need this function. |
| // |
| // Input: |
| // -samp_freq_hz : encoder sampling frequency. |
| // |
| // Return value: |
| // -1 if failed, or if this is meaningless for the given codec. |
| // 0 if succeeded. |
| // |
| virtual int16_t UpdateEncoderSampFreq( |
| uint16_t samp_freq_hz); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // EncoderSampFreq() |
| // Get the sampling frequency that the encoder (WebRtc wrapper) expects. |
| // |
| // Output: |
| // -samp_freq_hz : sampling frequency, in Hertz, which the encoder |
| // should be fed with. |
| // |
| // Return value: |
| // -1 if failed to output sampling rate. |
| // 0 if the sample rate is returned successfully. |
| // |
| virtual int16_t EncoderSampFreq(uint16_t& samp_freq_hz); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int32_t ConfigISACBandwidthEstimator() |
| // Call this function to configure the bandwidth estimator of ISAC. |
| // During the adaptation of bit-rate, iSAC automatically 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: |
| // -init_frame_fize_ms : initial frame-size in milliseconds. For iSAC-wb |
| // 30 ms and 60 ms (default) are acceptable values, |
| // and for iSAC-swb 30 ms is the only acceptable |
| // value. Zero indicates default value. |
| // -init_rate_bps : initial estimate of the bandwidth. Values |
| // between 10000 and 58000 are acceptable. |
| // -enforce_frame_size : 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 int32_t ConfigISACBandwidthEstimator( |
| const uint8_t init_frame_size_msec, |
| const uint16_t init_rate_bps, |
| const bool enforce_frame_size); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // 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 < max_payload_len_bytes * 8) and (B/T < max_rate_bit_per_sec), c.f. |
| // SetISACMaxRate(). |
| // |
| // Input: |
| // -max_payload_len_bytes : maximum payload size in bytes. |
| // |
| // Return value: |
| // -1 if failed to set the maximum payload-size. |
| // 0 if the given length is set successfully. |
| // |
| virtual int32_t SetISACMaxPayloadSize( |
| const uint16_t max_payload_len_bytes); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // 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 bits per |
| // second. Therefore, (B/T < max_rate_bit_per_sec) and |
| // (B < max_payload_len_bytes * 8) are always satisfied for iSAC payloads, |
| // c.f SetISACMaxPayloadSize(). |
| // |
| // Input: |
| // -max_rate_bps : 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 int32_t SetISACMaxRate(const uint32_t max_rate_bps); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // SaveDecoderParamS() |
| // Save the parameters of decoder. |
| // |
| // Input: |
| // -codec_params : pointer to a structure where the parameters of |
| // decoder is stored in. |
| // |
| void SaveDecoderParam(const WebRtcACMCodecParams* codec_params); |
| |
| int32_t FrameSize() { |
| return frame_len_smpl_; |
| } |
| |
| void SetIsMaster(bool is_master); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // REDPayloadISAC() |
| // This is an iSAC-specific function. The function is called to get RED |
| // payload from a default-encoder. |
| // |
| // Inputs: |
| // -isac_rate : the target rate of the main payload. A RED |
| // payload is generated according to the rate of |
| // main payload. Note that we are not specifying the |
| // rate of RED payload, but the main payload. |
| // -isac_bw_estimate : bandwidth information should be inserted in |
| // RED payload. |
| // |
| // Output: |
| // -payload : pointer to a buffer where the RED payload will |
| // written to. |
| // -payload_len_bytes : a place-holder to write the length of the RED |
| // payload in Bytes. |
| // |
| // Return value: |
| // -1 if an error occurs, otherwise the length of the payload (in Bytes) |
| // is returned. |
| // |
| virtual int16_t REDPayloadISAC(const int32_t isac_rate, |
| const int16_t isac_bw_estimate, |
| uint8_t* payload, |
| int16_t* payload_len_bytes); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // IsTrueStereoCodec() |
| // Call to see if current encoder is a true stereo codec. This function |
| // should be overwritten for codecs which are true stereo codecs |
| // Return value: |
| // -true if stereo codec |
| // -false if not stereo codec. |
| // |
| virtual bool IsTrueStereoCodec(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // HasFrameToEncode() |
| // Returns true if there is enough audio buffered for encoding, such that |
| // calling Encode() will return a payload. |
| // |
| bool HasFrameToEncode() const; |
| |
| protected: |
| /////////////////////////////////////////////////////////////////////////// |
| // All the functions with FunctionNameSafe(...) contain the actual |
| // implementation of FunctionName(...). FunctionName() acquires an |
| // appropriate lock and calls FunctionNameSafe() to do the actual work. |
| // Therefore, for the description of functionality, input/output arguments |
| // and return value we refer to FunctionName() |
| // |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See Decode() for the description of function, input(s)/output(s) and |
| // return value. |
| // |
| virtual int16_t DecodeSafe(uint8_t* bitstream, |
| int16_t bitstream_len_byte, |
| int16_t* audio, |
| int16_t* audio_samples, |
| int8_t* speech_type) = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See Add10MsSafe() for the description of function, input(s)/output(s) |
| // and return value. |
| // |
| virtual int32_t Add10MsDataSafe(const uint32_t timestamp, |
| const int16_t* data, |
| const uint16_t length, |
| const uint8_t audio_channel); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See RegisterInNetEq() for the description of function, |
| // input(s)/output(s) and return value. |
| // |
| virtual int32_t CodecDef(WebRtcNetEQ_CodecDef& codec_def, |
| const CodecInst& codec_inst) = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See EncoderParam() for the description of function, input(s)/output(s) |
| // and return value. |
| // |
| int16_t EncoderParamsSafe(WebRtcACMCodecParams *enc_params); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See DecoderParam for the description of function, input(s)/output(s) |
| // and return value. |
| // |
| // Note: |
| // Any Class where a single instance handle several flavors of the |
| // same codec, therefore, several payload types are associated with |
| // the same instance have to implement this function. |
| // |
| // Currently only iSAC is implementing it. A single iSAC instance is |
| // used for decoding both WB & SWB stream. At one moment both WB & SWB |
| // can be registered as receive codec. Hence two payloads are associated |
| // with a single codec instance. |
| // |
| virtual bool DecoderParamsSafe(WebRtcACMCodecParams *dec_params, |
| const uint8_t payload_type); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See ResetEncoder() for the description of function, input(s)/output(s) |
| // and return value. |
| // |
| int16_t ResetEncoderSafe(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See InitEncoder() for the description of function, input(s)/output(s) |
| // and return value. |
| // |
| int16_t InitEncoderSafe(WebRtcACMCodecParams *codec_params, |
| bool force_initialization); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See InitDecoder() for the description of function, input(s)/output(s) |
| // and return value. |
| // |
| int16_t InitDecoderSafe(WebRtcACMCodecParams *codec_params, |
| bool force_initialization); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See ResetDecoder() for the description of function, input(s)/output(s) |
| // and return value. |
| // |
| int16_t ResetDecoderSafe(int16_t payload_type); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See DestructEncoder() for the description of function, |
| // input(s)/output(s) and return value. |
| // |
| virtual void DestructEncoderSafe() = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See DestructDecoder() for the description of function, |
| // input(s)/output(s) and return value. |
| // |
| virtual void DestructDecoderSafe() = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See SetBitRate() for the description of function, input(s)/output(s) |
| // and return value. |
| // |
| // Any codec that can change the bit-rate has to implement this. |
| // |
| virtual int16_t SetBitRateSafe(const int32_t bitrate_bps); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See GetEstimatedBandwidth() for the description of function, |
| // input(s)/output(s) and return value. |
| // |
| virtual int32_t GetEstimatedBandwidthSafe(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See SetEstimatedBandwidth() for the description of function, |
| // input(s)/output(s) and return value. |
| // |
| virtual int32_t SetEstimatedBandwidthSafe( |
| int32_t estimated_bandwidth); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See GetRedPayload() for the description of function, input(s)/output(s) |
| // and return value. |
| // |
| virtual int32_t GetRedPayloadSafe(uint8_t* red_payload, |
| int16_t* payload_bytes); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See SetVAD() for the description of function, input(s)/output(s) and |
| // return value. |
| // |
| int16_t SetVADSafe(bool* enable_dtx, |
| bool* enable_vad, |
| ACMVADMode* mode); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See ReplaceInternalDTX() for the description of function, input and |
| // return value. |
| // |
| virtual int32_t ReplaceInternalDTXSafe(const bool replace_internal_dtx); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // See IsInternalDTXReplaced() for the description of function, input and |
| // return value. |
| // |
| virtual int32_t IsInternalDTXReplacedSafe(bool* internal_dtx_replaced); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t CreateEncoder() |
| // Creates the encoder instance. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| int16_t CreateEncoder(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t CreateDecoder() |
| // Creates the decoder instance. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| int16_t CreateDecoder(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t EnableVAD(); |
| // Enables VAD with the given mode. The VAD instance will be created if |
| // it does not exists. |
| // |
| // Input: |
| // -mode : VAD mode c.f. audio_coding_module_typedefs.h for |
| // the options. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| int16_t EnableVAD(ACMVADMode mode); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t DisableVAD() |
| // Disables VAD. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| int16_t DisableVAD(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t EnableDTX() |
| // Enables DTX. This method should be overwritten for codecs which have |
| // internal DTX. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| virtual int16_t EnableDTX(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t DisableDTX() |
| // Disables usage of DTX. This method should be overwritten for codecs which |
| // have internal DTX. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| virtual int16_t DisableDTX(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t InternalEncode() |
| // This is a codec-specific function called in EncodeSafe() to actually |
| // encode a frame of audio. |
| // |
| // Outputs: |
| // -bitstream : pointer to a buffer where the bit-stream is |
| // written to. |
| // -bitstream_len_byte : the length of the bit-stream in bytes, |
| // a negative value indicates error. |
| // |
| // Return value: |
| // -1 if failed, |
| // otherwise the length of the bit-stream is returned. |
| // |
| virtual int16_t InternalEncode(uint8_t* bitstream, |
| int16_t* bitstream_len_byte) = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t InternalInitEncoder() |
| // This is a codec-specific function called in InitEncoderSafe(), it has to |
| // do all codec-specific operation to initialize the encoder given the |
| // encoder parameters. |
| // |
| // Input: |
| // -codec_params : pointer to a structure that contains parameters to |
| // initialize encoder. |
| // Set codec_params->codec_inst.rate to -1 for |
| // iSAC to operate in adaptive mode. |
| // (to do: if frame-length is -1 frame-length will be |
| // automatically adjusted, otherwise, given |
| // frame-length is forced) |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| virtual int16_t InternalInitEncoder( |
| WebRtcACMCodecParams *codec_params) = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t InternalInitDecoder() |
| // This is a codec-specific function called in InitDecoderSafe(), it has to |
| // do all codec-specific operation to initialize the decoder given the |
| // decoder parameters. |
| // |
| // Input: |
| // -codec_params : pointer to a structure that contains parameters to |
| // initialize encoder. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| virtual int16_t InternalInitDecoder( |
| WebRtcACMCodecParams *codec_params) = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // void IncreaseNoMissedSamples() |
| // This method is called to increase the number of samples that are |
| // overwritten in the audio buffer. |
| // |
| // Input: |
| // -num_samples : the number of overwritten samples is incremented |
| // by this value. |
| // |
| void IncreaseNoMissedSamples(const int16_t num_samples); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t InternalCreateEncoder() |
| // This is a codec-specific method called in CreateEncoderSafe() it is |
| // supposed to perform all codec-specific operations to create encoder |
| // instance. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| virtual int16_t InternalCreateEncoder() = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t InternalCreateDecoder() |
| // This is a codec-specific method called in CreateDecoderSafe() it is |
| // supposed to perform all codec-specific operations to create decoder |
| // instance. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| virtual int16_t InternalCreateDecoder() = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // void InternalDestructEncoderInst() |
| // This is a codec-specific method, used in conferencing, called from |
| // DestructEncoderInst(). The input argument is pointer to encoder instance |
| // (codec instance for codecs that encoder and decoder share the same |
| // instance). This method is called to free the memory that |ptr_inst| is |
| // pointing to. |
| // |
| // Input: |
| // -ptr_inst : pointer to encoder instance. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| virtual void InternalDestructEncoderInst(void* ptr_inst) = 0; |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t InternalResetEncoder() |
| // This method is called to reset the states of encoder. However, the |
| // current parameters, e.g. frame-length, should remain as they are. For |
| // most of the codecs a re-initialization of the encoder is what needs to |
| // be down. But for iSAC we like to keep the BWE history so we cannot |
| // re-initialize. As soon as such an API is implemented in iSAC this method |
| // has to be overwritten in ACMISAC class. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| virtual int16_t InternalResetEncoder(); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // int16_t ProcessFrameVADDTX() |
| // This function is called when a full frame of audio is available. It will |
| // break the audio frame into blocks such that each block could be processed |
| // by VAD & CN/DTX. If a frame is divided into two blocks then there are two |
| // cases. First, the first block is active, the second block will not be |
| // processed by CN/DTX but only by VAD and return to caller with |
| // '*samples_processed' set to zero. There, the audio frame will be encoded |
| // by the encoder. Second, the first block is inactive and is processed by |
| // CN/DTX, then we stop processing the next block and return to the caller |
| // which is EncodeSafe(), with "*samples_processed" equal to the number of |
| // samples in first block. |
| // |
| // Output: |
| // -bitstream : pointer to a buffer where DTX frame, if |
| // generated, will be written to. |
| // -bitstream_len_byte : contains the length of bit-stream in bytes, if |
| // generated. Zero if no bit-stream is generated. |
| // -samples_processed : contains no of samples that actually CN has |
| // processed. Those samples processed by CN will not |
| // be encoded by the encoder, obviously. If |
| // contains zero, it means that the frame has been |
| // identified as active by VAD. Note that |
| // "*samples_processed" might be non-zero but |
| // "*bitstream_len_byte" be zero. |
| // |
| // Return value: |
| // -1 if failed, |
| // 0 if succeeded. |
| // |
| int16_t ProcessFrameVADDTX(uint8_t* bitstream, |
| int16_t* bitstream_len_byte, |
| int16_t* samples_processed); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // CanChangeEncodingParam() |
| // Check if the codec parameters can be changed. In conferencing normally |
| // codec parameters cannot be changed. The exception is bit-rate of isac. |
| // |
| // return value: |
| // -true if codec parameters are allowed to change. |
| // -false otherwise. |
| // |
| virtual bool CanChangeEncodingParam(CodecInst& codec_inst); |
| |
| /////////////////////////////////////////////////////////////////////////// |
| // CurrentRate() |
| // Call to get the current encoding rate of the encoder. This function |
| // should be overwritten for codecs which automatically change their |
| // target rate. One example is iSAC. The output of the function is the |
| // current target rate. |
| // |
| // Output: |
| // -rate_bps : the current target rate of the codec. |
| // |
| virtual void CurrentRate(int32_t& /* rate_bps */); |
| |
| virtual void SaveDecoderParamSafe(const WebRtcACMCodecParams* codec_params); |
| |
| // &in_audio_[in_audio_ix_write_] always point to where new audio can be |
| // written to |
| int16_t in_audio_ix_write_; |
| |
| // &in_audio_[in_audio_ix_read_] points to where audio has to be read from |
| int16_t in_audio_ix_read_; |
| |
| int16_t in_timestamp_ix_write_; |
| |
| // Where the audio is stored before encoding, |
| // To save memory the following buffer can be allocated |
| // dynamically for 80 ms depending on the sampling frequency |
| // of the codec. |
| int16_t* in_audio_; |
| uint32_t* in_timestamp_; |
| |
| int16_t frame_len_smpl_; |
| uint16_t num_channels_; |
| |
| // This will point to a static database of the supported codecs |
| int16_t codec_id_; |
| |
| // This will account for the number of samples were not encoded |
| // the case is rare, either samples are missed due to overwrite |
| // at input buffer or due to encoding error |
| uint32_t num_missed_samples_; |
| |
| // True if the encoder instance created |
| bool encoder_exist_; |
| bool decoder_exist_; |
| // True if the encoder instance initialized |
| bool encoder_initialized_; |
| bool decoder_initialized_; |
| |
| bool registered_in_neteq_; |
| |
| // VAD/DTX |
| bool has_internal_dtx_; |
| WebRtcVadInst* ptr_vad_inst_; |
| bool vad_enabled_; |
| ACMVADMode vad_mode_; |
| int16_t vad_label_[MAX_FRAME_SIZE_10MSEC]; |
| bool dtx_enabled_; |
| WebRtcCngEncInst* ptr_dtx_inst_; |
| uint8_t num_lpc_params_; |
| bool sent_cn_previous_; |
| bool is_master_; |
| int16_t prev_frame_cng_; |
| |
| WebRtcACMCodecParams encoder_params_; |
| WebRtcACMCodecParams decoder_params_; |
| |
| // Used as a global lock for all available decoders |
| // so that no decoder is used when NetEQ decodes. |
| RWLockWrapper* neteq_decode_lock_; |
| // Used to lock wrapper internal data |
| // such as buffers and state variables. |
| RWLockWrapper& codec_wrapper_lock_; |
| |
| uint32_t last_encoded_timestamp_; |
| uint32_t last_timestamp_; |
| bool is_audio_buff_fresh_; |
| uint32_t unique_id_; |
| }; |
| |
| } // namespace acm1 |
| |
| } // namespace webrtc |
| |
| #endif // WEBRTC_MODULES_AUDIO_CODING_MAIN_SOURCE_ACM_GENERIC_CODEC_H_ |
