/* * 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 ACM_GENERIC_CODEC_H #define ACM_GENERIC_CODEC_H #include "acm_common_defs.h" #include "audio_coding_module_typedefs.h" #include "rw_lock_wrapper.h" #include "trace.h" #include "webrtc_neteq.h" #define MAX_FRAME_SIZE_10MSEC 6 // forward declaration struct WebRtcVadInst; struct WebRtcCngEncInst; namespace webrtc { // forward declaration struct CodecInst; 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; /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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 "*encodingType" will be either // "activeNormalEncode" or "passiveNormalEncode" 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. // -bitStreamLenByte : 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). // -encodingType : 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. // WebRtc_Word16 Encode( WebRtc_UWord8* bitStream, WebRtc_Word16* bitStreamLenByte, WebRtc_UWord32* timeStamp, WebRtcACMEncodingType* encodingType); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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. // -bitStreamLenByte : the length of the bit-stream in bytes. // // Outputs: // -audio : pointer to a buffer where the audio will written. // -audioSamples : number of audio samples out of decoding the given // bit-stream. // -speechType : speech type (for future use). // // Return value: // -1 if failed to decode, // 0 if succeeded. // WebRtc_Word16 Decode( WebRtc_UWord8* bitStream, WebRtc_Word16 bitStreamLenByte, WebRtc_Word16* audio, WebRtc_Word16* audioSamples, WebRtc_Word8* speechType); /////////////////////////////////////////////////////////////////////////// // 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(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 EncoderParams() // It is called to get encoder parameters. It will call // EncoderParamsSafe() in turn. // // Output: // -encParams : 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. // // WebRtc_Word16 EncoderParams( WebRtcACMCodecParams *encParams); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 DecoderParams(...) // It is called to get decoder parameters. It will call DecoderParamsSafe() // in turn. // // Output: // -decParams : 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 *decParams, const WebRtc_UWord8 payloadType); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 InitEncoder(...) // This function is called to initialize the encoder with the given // parameters. // // Input: // -codecParams : parameters of encoder. // -forceInitialization: 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. // // WebRtc_Word16 InitEncoder( WebRtcACMCodecParams* codecParams, bool forceInitialization); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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: // -codecParams : parameters of decoder. // -forceInitialization: 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. // // WebRtc_Word16 InitDecoder( WebRtcACMCodecParams* codecParams, bool forceInitialization); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word32 RegisterInNetEq(...) // This function is called to register the decoder in NetEq, with the given // payload-type. // // Inputs: // -netEq : pointer to NetEq Instance // -codecInst : instance with of the codec settings of the codec // // Return values // -1 if failed to register, // 0 if successfully initialized. // WebRtc_Word32 RegisterInNetEq( ACMNetEQ* netEq, const CodecInst& codecInst); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word32 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 // -audioChannel : 0 for mono, 1 for stereo (not supported yet) // // Return values: // -1 if failed // 0 otherwise. // WebRtc_Word32 Add10MsData( const WebRtc_UWord32 timeStamp, const WebRtc_Word16* data, const WebRtc_UWord16 length, const WebRtc_UWord8 audioChannel); /////////////////////////////////////////////////////////////////////////// // WebRtc_UWord32 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. // WebRtc_UWord32 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(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 SetBitRate() // The function is called to set the encoding rate. // // Input: // -bitRateBPS : 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 // WebRtc_Word16 SetBitRate(const WebRtc_Word32 bitRateBPS); /////////////////////////////////////////////////////////////////////////// // DestructEncoderInst() // This API is used in conferencing. It will free the memory that is pointed // by "ptrInst". "ptrInst" is a pointer to encoder instance, created and // filled up by calling EncoderInst(...). // // Inputs: // -ptrInst : pointer to an encoder instance to be deleted. // // void DestructEncoderInst( void* ptrInst); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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: // -audioBuff : 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. // WebRtc_Word16 AudioBuffer( WebRtcACMAudioBuff& audioBuff); /////////////////////////////////////////////////////////////////////////// // WebRtc_UWord32 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. // WebRtc_UWord32 EarliestTimestamp() const; /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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. // WebRtc_Word16 SetAudioBuffer(WebRtcACMAudioBuff& audioBuff); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 SetVAD() // This is called to set VAD & DTX. If the codec has internal DTX that 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. // // Inputs: // -enableDTX : 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. // -enableVAD : 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 // "enableVAD." // -mode : this specifies the aggressiveness of VAD. // // Return value // -1 if failed to set DTX & VAD as specified, // 0 if succeeded. // WebRtc_Word16 SetVAD( const bool enableDTX = true, const bool enableVAD = false, const ACMVADMode mode = VADNormal); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word32 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: // -replaceInternalDTX : if true the internal DTX is replaced with WebRtc. // // Return value // -1 if failed to replace internal DTX, // 0 if succeeded. // WebRtc_Word32 ReplaceInternalDTX(const bool replaceInternalDTX); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word32 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: // -internalDTXReplaced : if true the internal DTX is replaced with WebRtc. // // Return value // -1 if failed to check if replace internal DTX or replacement not feasible, // 0 if succeeded. // WebRtc_Word32 IsInternalDTXReplaced(bool* internalDTXReplaced); /////////////////////////////////////////////////////////////////////////// // void SetNetEqDecodeLock() // Passes the NetEq lock to the codec. // // Input: // -netEqDecodeLock : pointer to the lock associated with NetEQ of ACM. // void SetNetEqDecodeLock( RWLockWrapper* netEqDecodeLock) { _netEqDecodeLock = netEqDecodeLock; } /////////////////////////////////////////////////////////////////////////// // 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 _hasInternalDTX; } /////////////////////////////////////////////////////////////////////////// // WebRtc_Word32 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. // WebRtc_Word32 GetEstimatedBandwidth(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word32 SetEstimatedBandwidth() // Used to set estiamted bandwidth sent out of band from other side. Only // iSAC will have use for the value. // // Input: // -estimatedBandwidth: estimated bandwidth in bits/sec // // Return value: // -1 if fails to set estimated bandwidth, // 0 on success. // WebRtc_Word32 SetEstimatedBandwidth(WebRtc_Word32 estimatedBandwidth); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word32 GetRedPayload() // Used to get codec specific RED payload (if such is implemented). // Currently only done in iSAC. // // Outputs: // -redPayload : a pointer to the data for RED payload. // -payloadBytes : number of bytes in RED payload. // // Return value: // -1 if fails to get codec specific RED, // 0 if succeeded. // WebRtc_Word32 GetRedPayload( WebRtc_UWord8* redPayload, WebRtc_Word16* payloadBytes); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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. // WebRtc_Word16 ResetEncoder(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 ResetEncoder() // By calling this function you would re-initialize the decoder with the // current parameters. // // Return value // -1 if failed, // 0 if succeeded. // WebRtc_Word16 ResetDecoder( WebRtc_Word16 payloadType); /////////////////////////////////////////////////////////////////////////// // 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(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 SamplesLeftToEncode() // Returns the number of samples required to be able to do encoding. // // Return value: // Number of samples. // WebRtc_Word16 SamplesLeftToEncode(); /////////////////////////////////////////////////////////////////////////// // WebRtc_UWord32 LastEncodedTimestamp() // Returns the timestamp of the last frame it encoded. // // Return value: // Timestamp. // WebRtc_UWord32 LastEncodedTimestamp() const; /////////////////////////////////////////////////////////////////////////// // WebRtc_Word32 UnregisterFromNetEq() // To remove the codec from NetEQ. If the codec (or the decoder instance) // is going to be deleted, first the codec has to be removed from NetEq // by calling this function. // // Input: // -netEq : pointer to a NetEq instance that the codec // has to be unregistered from. // // Output: // -1 if failed to unregister the codec, // 0 if the codec is successfully unregistered. // WebRtc_Word32 UnregisterFromNetEq( ACMNetEQ* netEq, WebRtc_Word16 payloadType); /////////////////////////////////////////////////////////////////////////// // SetUniqueID() // Set a unique ID for the codec to be used for tracing and debuging // // Input // -id : A number to identify the codec. // void SetUniqueID( const WebRtc_UWord32 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 flavers 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 funtion 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 flaver of the // codec in codec database. For instance, if we just got a SWB payload then // the input parameter is ACMCodecDB::isacswb. // // Input: // -codecId : 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 WebRtc_Word16 UpdateDecoderSampFreq( WebRtc_Word16 /* codecId */) { return 0; } /////////////////////////////////////////////////////////////////////////// // 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: // -encoderSampFreqHz : encoder sampling frequency. // // Return value: // -1 if failed, or if this is meaningless for the given codec. // 0 if succeeded. // virtual WebRtc_Word16 UpdateEncoderSampFreq( WebRtc_UWord16 encoderSampFreqHz); /////////////////////////////////////////////////////////////////////////// // EncoderSampFreq() // Get the sampling frequency that the encoder (WebRtc wrapper) expects. // // Output: // -sampFreqHz : 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 WebRtc_Word16 EncoderSampFreq( WebRtc_UWord16& sampFreqHz); /////////////////////////////////////////////////////////////////////////// // 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); /////////////////////////////////////////////////////////////////////////// // 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); /////////////////////////////////////////////////////////////////////////// // 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); /////////////////////////////////////////////////////////////////////////// // SaveDecoderParamS() // Save the parameters of decoder. // // Input: // -codecParams : pointer to a struct where the parameters of // decoder is stored in. // void SaveDecoderParam( const WebRtcACMCodecParams* codecParams); WebRtc_Word32 FrameSize() { return _frameLenSmpl; } void SetIsMaster(bool isMaster); /////////////////////////////////////////////////////////////////////////// // REDPayloadISAC() // This is an iSAC-specific function. The function is called to get RED // paylaod from a default-encoder. // // Inputs: // -isacRate : the target rate of the main payload. A RED // paylaod is generated according to the rate of // main paylaod. Note that we are not specifying the // rate of RED payload, but the main payload. // -isacBwEstimate : bandwidth information should be inserted in // RED payload. // // Output: // -payload : pointer to a buffer where the RED paylaod will // written to. // -paylaodLenBytes : a place-holder to write the length of the RED // payload in Bytes. // // Return value: // -1 if an error occures, otherwise the length of the payload (in Bytes) // is returned. // // virtual WebRtc_Word16 REDPayloadISAC( const WebRtc_Word32 isacRate, const WebRtc_Word16 isacBwEstimate, WebRtc_UWord8* payload, WebRtc_Word16* payloadLenBytes); 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 Encode() for the description of function, input(s)/output(s) and // return value. // WebRtc_Word16 EncodeSafe( WebRtc_UWord8* bitStream, WebRtc_Word16* bitStreamLenByte, WebRtc_UWord32* timeStamp, WebRtcACMEncodingType* encodingType); /////////////////////////////////////////////////////////////////////////// // See Decode() for the description of function, input(s)/output(s) and // return value. // virtual WebRtc_Word16 DecodeSafe( WebRtc_UWord8* bitStream, WebRtc_Word16 bitStreamLenByte, WebRtc_Word16* audio, WebRtc_Word16* audioSamples, WebRtc_Word8* speechType) = 0; /////////////////////////////////////////////////////////////////////////// // See Add10MsSafe() for the description of function, input(s)/output(s) // and return value. // virtual WebRtc_Word32 Add10MsDataSafe( const WebRtc_UWord32 timeStamp, const WebRtc_Word16* data, const WebRtc_UWord16 length, const WebRtc_UWord8 audioChannel); /////////////////////////////////////////////////////////////////////////// // See RegisterInNetEq() for the description of function, // input(s)/output(s) and return value. // virtual WebRtc_Word32 CodecDef( WebRtcNetEQ_CodecDef& codecDef, const CodecInst& codecInst) = 0; /////////////////////////////////////////////////////////////////////////// // See EncoderParam() for the description of function, input(s)/output(s) // and return value. // WebRtc_Word16 EncoderParamsSafe( WebRtcACMCodecParams *encParams); /////////////////////////////////////////////////////////////////////////// // See DecoderParam for the description of function, input(s)/output(s) // and return value. // // Note: // Any Class where a single instance handle several flavers 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 *decParams, const WebRtc_UWord8 payloadType); /////////////////////////////////////////////////////////////////////////// // See ResetEncoder() for the description of function, input(s)/output(s) // and return value. // WebRtc_Word16 ResetEncoderSafe(); /////////////////////////////////////////////////////////////////////////// // See InitEncoder() for the description of function, input(s)/output(s) // and return value. // WebRtc_Word16 InitEncoderSafe( WebRtcACMCodecParams *codecParams, bool forceInitialization); /////////////////////////////////////////////////////////////////////////// // See InitDecoder() for the description of function, input(s)/output(s) // and return value. // WebRtc_Word16 InitDecoderSafe( WebRtcACMCodecParams *codecParams, bool forceInitialization); /////////////////////////////////////////////////////////////////////////// // See ResetDecoder() for the description of function, input(s)/output(s) // and return value. // WebRtc_Word16 ResetDecoderSafe( WebRtc_Word16 payloadType); /////////////////////////////////////////////////////////////////////////// // 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 WebRtc_Word16 SetBitRateSafe( const WebRtc_Word32 bitRateBPS); /////////////////////////////////////////////////////////////////////////// // See GetEstimatedBandwidth() for the description of function, input(s)/output(s) // and return value. // virtual WebRtc_Word32 GetEstimatedBandwidthSafe(); /////////////////////////////////////////////////////////////////////////// // See SetEstimatedBandwidth() for the description of function, input(s)/output(s) // and return value. // virtual WebRtc_Word32 SetEstimatedBandwidthSafe(WebRtc_Word32 estimatedBandwidth); /////////////////////////////////////////////////////////////////////////// // See GetRedPayload() for the description of function, input(s)/output(s) // and return value. // virtual WebRtc_Word32 GetRedPayloadSafe( WebRtc_UWord8* redPayload, WebRtc_Word16* payloadBytes); /////////////////////////////////////////////////////////////////////////// // See SetVAD() for the description of function, input(s)/output(s) and // return value. // WebRtc_Word16 SetVADSafe( const bool enableDTX = true, const bool enableVAD = false, const ACMVADMode mode = VADNormal); /////////////////////////////////////////////////////////////////////////// // See ReplaceInternalDTX() for the description of function, input and // return value. // virtual WebRtc_Word32 ReplaceInternalDTXSafe( const bool replaceInternalDTX); /////////////////////////////////////////////////////////////////////////// // See IsInternalDTXReplaced() for the description of function, input and // return value. // virtual WebRtc_Word32 IsInternalDTXReplacedSafe( bool* internalDTXReplaced); /////////////////////////////////////////////////////////////////////////// // See UnregisterFromNetEq() for the description of function, // input(s)/output(s) and return value. // virtual WebRtc_Word16 UnregisterFromNetEqSafe( ACMNetEQ* netEq, WebRtc_Word16 payloadType) = 0; /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 CreateEncoder() // Creates the encoder instance. // // Return value: // -1 if failed, // 0 if succeeded. // WebRtc_Word16 CreateEncoder(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 CreateDecoder() // Creates the decoder instance. // // Return value: // -1 if failed, // 0 if succeeded. // WebRtc_Word16 CreateDecoder(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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. // WebRtc_Word16 EnableVAD(ACMVADMode mode); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 DisableVAD() // Disables VAD. // // Return value: // -1 if failed, // 0 if succeeded. // WebRtc_Word16 DisableVAD(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 EnableDTX() // Enables DTX. This method should be overwritten for codecs which have // internal DTX. // // Return value: // -1 if failed, // 0 if succeeded. // virtual WebRtc_Word16 EnableDTX(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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 WebRtc_Word16 DisableDTX(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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. // -bitStreamLenByte : the length of the bit-stream in byte, a negative // value indicates error. // // Return value: // -1 if failed, // otherwise the length of the bit-stream is returned. // virtual WebRtc_Word16 InternalEncode( WebRtc_UWord8* bitStream, WebRtc_Word16* bitStreamLenByte) = 0; /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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: // -codecParams : pointer to a structure that contains parameters to // initialize encoder. // Set codecParam->CodecInst.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 WebRtc_Word16 InternalInitEncoder( WebRtcACMCodecParams *codecParams) = 0; /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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: // -codecParams : pointer to a structure that contains parameters to // initialize encoder. // // Return value: // -1 if failed, // 0 if succeeded. // virtual WebRtc_Word16 InternalInitDecoder( WebRtcACMCodecParams *codecParams) = 0; /////////////////////////////////////////////////////////////////////////// // void IncreaseNoMissedSamples() // This method is called to increase the number of samples that are // overwritten in the audio buffer. // // Input: // -noSamples : the number of overwritten samples is incremented // by this value. // void IncreaseNoMissedSamples( const WebRtc_Word16 noSamples); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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 WebRtc_Word16 InternalCreateEncoder() = 0; /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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 WebRtc_Word16 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 "ptrInst" is // pointing to. // // Input: // -ptrInst : pointer to encoder instance. // // Return value: // -1 if failed, // 0 if succeeded. // virtual void InternalDestructEncoderInst( void* ptrInst) = 0; /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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 WebRtc_Word16 InternalResetEncoder(); /////////////////////////////////////////////////////////////////////////// // WebRtc_Word16 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 // '*samplesProcessed' 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 "*samplesProcessed" equal to the number of // samples in first block. // // Output: // -bitStream : pointer to a buffer where DTX frame, if // generated, will be written to. // -bitStreamLenByte : contains the length of bit-stream in bytes, if // generated. Zero if no bit-stream is generated. // -noSamplesProcessed : 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 // "*noSamplesProcessed" might be non-zero but // "*bitStreamLenByte" be zero. // // Return value: // -1 if failed, // 0 if succeeded. // WebRtc_Word16 ProcessFrameVADDTX( WebRtc_UWord8* bitStream, WebRtc_Word16* bitStreamLenByte, WebRtc_Word16* samplesProcessed); /////////////////////////////////////////////////////////////////////////// // CanChangeEncodingParam() // Check if the codec parameters can be changed. In conferencing normally // codec parametrs cannot be changed. The exception is bit-rate of isac. // // return value: // -true if codec parameters are allowed to change. // -flase otherwise. // virtual bool CanChangeEncodingParam(CodecInst& codecInst); /////////////////////////////////////////////////////////////////////////// // CurrentRate() // Call to get the current encoding rate of the encoder. This function // should be overwritten for codecs whic automatically change their // target rate. One example is iSAC. The output of the function is the // current target rate. // // Output: // -rateBitPerSec : the current target rate of the codec. // virtual void CurrentRate( WebRtc_Word32& /* rateBitPerSec */) { return; } virtual void SaveDecoderParamSafe( const WebRtcACMCodecParams* codecParams); // &_inAudio[_inAudioIxWrite] always point to where new audio can be // written to WebRtc_Word16 _inAudioIxWrite; // &_inAudio[_inAudioIxRead] points to where audio has to be read from WebRtc_Word16 _inAudioIxRead; WebRtc_Word16 _inTimestampIxWrite; // Where the audio is stored before encoding, // To save memory the following buffer can be allocated // dynamically for 80ms depending on the sampling frequency // of the codec. WebRtc_Word16* _inAudio; WebRtc_UWord32* _inTimestamp; WebRtc_Word16 _frameLenSmpl; WebRtc_UWord16 _noChannels; // This will point to a static database of the supported codecs WebRtc_Word16 _codecID; // This will account for the No of samples were not encoded // the case is rare, either samples are missed due to overwite // at input buffer or due to encoding error WebRtc_UWord32 _noMissedSamples; // True if the encoder instance created bool _encoderExist; bool _decoderExist; // True if the ecncoder instance initialized bool _encoderInitialized; bool _decoderInitialized; bool _registeredInNetEq; // VAD/DTX bool _hasInternalDTX; WebRtcVadInst* _ptrVADInst; bool _vadEnabled; ACMVADMode _vadMode; WebRtc_Word16 _vadLabel[MAX_FRAME_SIZE_10MSEC]; bool _dtxEnabled; WebRtcCngEncInst* _ptrDTXInst; WebRtc_UWord8 _numLPCParams; bool _sentCNPrevious; bool _isMaster; WebRtcACMCodecParams _encoderParams; WebRtcACMCodecParams _decoderParams; // Used as a global lock for all avaiable decoders // so that no decoder is used when NetEQ decodes. RWLockWrapper* _netEqDecodeLock; // Used to lock wrapper internal data // such as buffers and state variables. RWLockWrapper& _codecWrapperLock; WebRtc_UWord32 _lastEncodedTimestamp; WebRtc_UWord32 _lastTimestamp; bool _isAudioBuffFresh; WebRtc_UWord32 _uniqueID; }; } // namespace webrt #endif // ACM_GENERIC_CODEC_H