2 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
4 * Use of this source code is governed by a BSD-style license
5 * that can be found in the LICENSE file in the root of the source
6 * tree. An additional intellectual property rights grant can be found
7 * in the file PATENTS. All contributing project authors may
8 * be found in the AUTHORS file in the root of the source tree.
11 #ifndef WEBRTC_MODULES_AUDIO_CODING_MAIN_ACM2_ACM_GENERIC_CODEC_H_
12 #define WEBRTC_MODULES_AUDIO_CODING_MAIN_ACM2_ACM_GENERIC_CODEC_H_
14 #include "webrtc/base/thread_annotations.h"
15 #include "webrtc/modules/audio_coding/main/interface/audio_coding_module_typedefs.h"
16 #include "webrtc/modules/audio_coding/main/acm2/acm_common_defs.h"
17 #include "webrtc/modules/audio_coding/neteq/interface/neteq.h"
18 #include "webrtc/modules/audio_coding/neteq/interface/audio_decoder.h"
19 #include "webrtc/system_wrappers/interface/rw_lock_wrapper.h"
20 #include "webrtc/system_wrappers/interface/trace.h"
22 #define MAX_FRAME_SIZE_10MSEC 6
24 // forward declaration
26 struct WebRtcCngEncInst;
30 struct WebRtcACMCodecParams;
35 // forward declaration
38 class ACMGenericCodec {
40 ///////////////////////////////////////////////////////////////////////////
41 // Constructor of the class
45 ///////////////////////////////////////////////////////////////////////////
46 // Destructor of the class.
48 virtual ~ACMGenericCodec();
50 ///////////////////////////////////////////////////////////////////////////
51 // ACMGenericCodec* CreateInstance();
52 // The function will be used for FEC. It is not implemented yet.
54 virtual ACMGenericCodec* CreateInstance() = 0;
56 ///////////////////////////////////////////////////////////////////////////
58 // The function is called to perform an encoding of the audio stored in
59 // audio buffer. An encoding is performed only if enough audio, i.e. equal
60 // to the frame-size of the codec, exist. The audio frame will be processed
61 // by VAD and CN/DTX if required. There are few different cases.
63 // A) Neither VAD nor DTX is active; the frame is encoded by the encoder.
65 // B) VAD is enabled but not DTX; in this case the audio is processed by VAD
66 // and encoded by the encoder. The "*encoding_type" will be either
67 // "kActiveNormalEncode" or "kPassiveNormalEncode" if frame is active or
68 // passive, respectively.
70 // C) DTX is enabled; if the codec has internal VAD/DTX we just encode the
71 // frame by the encoder. Otherwise, the frame is passed through VAD and
72 // if identified as passive, then it will be processed by CN/DTX. If the
73 // frame is active it will be encoded by the encoder.
75 // This function acquires the appropriate locks and calls EncodeSafe() for
76 // the actual processing.
79 // -bitstream : a buffer where bit-stream will be written to.
80 // -bitstream_len_byte : contains the length of the bit-stream in
82 // -timestamp : contains the RTP timestamp, this is the
83 // sampling time of the first sample encoded
84 // (measured in number of samples).
85 // -encoding_type : contains the type of encoding applied on the
86 // audio samples. The alternatives are
87 // (c.f. acm_common_types.h)
89 // there was not enough data to encode. or
90 // some error has happened that we could
92 // -kActiveNormalEncoded:
93 // the audio frame is active and encoded by
95 // -kPassiveNormalEncoded:
96 // the audio frame is passive but coded with
97 // the given codec (NO DTX).
99 // The audio frame is passive and used
100 // wide-band CN to encode.
102 // The audio frame is passive and used
103 // narrow-band CN to encode.
106 // -1 if error is occurred, otherwise the length of the bit-stream in
109 int16_t Encode(uint8_t* bitstream,
110 int16_t* bitstream_len_byte,
112 WebRtcACMEncodingType* encoding_type);
114 ///////////////////////////////////////////////////////////////////////////
115 // bool EncoderInitialized();
118 // True if the encoder is successfully initialized,
121 bool EncoderInitialized();
123 ///////////////////////////////////////////////////////////////////////////
124 // int16_t EncoderParams()
125 // It is called to get encoder parameters. It will call
126 // EncoderParamsSafe() in turn.
129 // -enc_params : a buffer where the encoder parameters is
130 // written to. If the encoder is not
131 // initialized this buffer is filled with
134 // -1 if the encoder is not initialized,
137 int16_t EncoderParams(WebRtcACMCodecParams* enc_params);
139 ///////////////////////////////////////////////////////////////////////////
140 // int16_t InitEncoder(...)
141 // This function is called to initialize the encoder with the given
145 // -codec_params : parameters of encoder.
146 // -force_initialization: if false the initialization is invoked only if
147 // the encoder is not initialized. If true the
148 // encoder is forced to (re)initialize.
151 // 0 if could initialize successfully,
152 // -1 if failed to initialize.
155 int16_t InitEncoder(WebRtcACMCodecParams* codec_params,
156 bool force_initialization);
158 ///////////////////////////////////////////////////////////////////////////
159 // int32_t Add10MsData(...)
160 // This function is called to add 10 ms of audio to the audio buffer of
164 // -timestamp : the timestamp of the 10 ms audio. the timestamp
165 // is the sampling time of the
166 // first sample measured in number of samples.
167 // -data : a buffer that contains the audio. The codec
168 // expects to get the audio in correct sampling
170 // -length : the length of the audio buffer
171 // -audio_channel : 0 for mono, 1 for stereo (not supported yet)
177 int32_t Add10MsData(const uint32_t timestamp,
179 const uint16_t length,
180 const uint8_t audio_channel);
182 ///////////////////////////////////////////////////////////////////////////
183 // uint32_t NoMissedSamples()
184 // This function returns the number of samples which are overwritten in
185 // the audio buffer. The audio samples are overwritten if the input audio
186 // buffer is full, but Add10MsData() is called. (We might remove this
187 // function if it is not used)
190 // Number of samples which are overwritten.
192 uint32_t NoMissedSamples() const;
194 ///////////////////////////////////////////////////////////////////////////
195 // void ResetNoMissedSamples()
196 // This function resets the number of overwritten samples to zero.
197 // (We might remove this function if we remove NoMissedSamples())
199 void ResetNoMissedSamples();
201 ///////////////////////////////////////////////////////////////////////////
202 // int16_t SetBitRate()
203 // The function is called to set the encoding rate.
206 // -bitrate_bps : encoding rate in bits per second
209 // -1 if failed to set the rate, due to invalid input or given
210 // codec is not rate-adjustable.
211 // 0 if the rate is adjusted successfully
213 int16_t SetBitRate(const int32_t bitrate_bps);
215 ///////////////////////////////////////////////////////////////////////////
216 // uint32_t EarliestTimestamp()
217 // Returns the timestamp of the first 10 ms in audio buffer. This is used
218 // to identify if a synchronization of two encoders is required.
221 // timestamp of the first 10 ms audio in the audio buffer.
223 uint32_t EarliestTimestamp() const;
225 ///////////////////////////////////////////////////////////////////////////
227 // This is called to set VAD & DTX. If the codec has internal DTX, it will
228 // be used. If DTX is enabled and the codec does not have internal DTX,
229 // WebRtc-VAD will be used to decide if the frame is active. If DTX is
230 // disabled but VAD is enabled, the audio is passed through VAD to label it
231 // as active or passive, but the frame is encoded normally. However the
232 // bit-stream is labeled properly so that ACM::Process() can use this
233 // information. In case of failure, the previous states of the VAD & DTX
237 // -enable_dtx : if true DTX will be enabled otherwise the DTX is
238 // disabled. If codec has internal DTX that will be
239 // used, otherwise WebRtc-CNG is used. In the latter
240 // case VAD is automatically activated.
241 // -enable_vad : if true WebRtc-VAD is enabled, otherwise VAD is
242 // disabled, except for the case that DTX is enabled
243 // but codec doesn't have internal DTX. In this case
244 // VAD is enabled regardless of the value of
246 // -mode : this specifies the aggressiveness of VAD.
249 // -1 if failed to set DTX & VAD as specified,
252 int16_t SetVAD(bool* enable_dtx, bool* enable_vad, ACMVADMode* mode);
254 ///////////////////////////////////////////////////////////////////////////
255 // int32_t ReplaceInternalDTX()
256 // This is called to replace the codec internal DTX with WebRtc DTX.
257 // This is only valid for G729 where the user has possibility to replace
258 // AnnexB with WebRtc DTX. For other codecs this function has no effect.
261 // -replace_internal_dtx : if true the internal DTX is replaced with WebRtc.
264 // -1 if failed to replace internal DTX,
267 int32_t ReplaceInternalDTX(const bool replace_internal_dtx);
269 ///////////////////////////////////////////////////////////////////////////
270 // int32_t IsInternalDTXReplaced()
271 // This is called to check if the codec internal DTX is replaced by WebRtc
272 // DTX. This is only valid for G729 where the user has possibility to replace
273 // AnnexB with WebRtc DTX. For other codecs this function has no effect.
276 // -internal_dtx_replaced: if true the internal DTX is replaced with WebRtc.
279 // -1 if failed to check
282 int32_t IsInternalDTXReplaced(bool* internal_dtx_replaced);
284 ///////////////////////////////////////////////////////////////////////////
285 // bool HasInternalDTX()
286 // Used to check if the codec has internal DTX.
289 // true if the codec has an internal DTX, e.g. G729,
292 bool HasInternalDTX() const {
293 ReadLockScoped rl(codec_wrapper_lock_);
294 return has_internal_dtx_;
297 ///////////////////////////////////////////////////////////////////////////
298 // int32_t GetEstimatedBandwidth()
299 // Used to get decoder estimated bandwidth. Only iSAC will provide a value.
303 // -1 if fails to get decoder estimated bandwidth,
304 // >0 estimated bandwidth in bits/sec.
306 int32_t GetEstimatedBandwidth();
308 ///////////////////////////////////////////////////////////////////////////
309 // int32_t SetEstimatedBandwidth()
310 // Used to set estiamted bandwidth sent out of band from other side. Only
311 // iSAC will have use for the value.
314 // -estimated_bandwidth: estimated bandwidth in bits/sec
317 // -1 if fails to set estimated bandwidth,
320 int32_t SetEstimatedBandwidth(int32_t estimated_bandwidth);
322 ///////////////////////////////////////////////////////////////////////////
323 // int32_t GetRedPayload()
324 // Used to get codec specific RED payload (if such is implemented).
325 // Currently only done in iSAC.
328 // -red_payload : a pointer to the data for RED payload.
329 // -payload_bytes : number of bytes in RED payload.
332 // -1 if fails to get codec specific RED,
335 int32_t GetRedPayload(uint8_t* red_payload, int16_t* payload_bytes);
337 ///////////////////////////////////////////////////////////////////////////
338 // int16_t ResetEncoder()
339 // By calling this function you would re-initialize the encoder with the
340 // current parameters. All the settings, e.g. VAD/DTX, frame-size... should
341 // remain unchanged. (In case of iSAC we don't want to lose BWE history.)
347 int16_t ResetEncoder();
349 ///////////////////////////////////////////////////////////////////////////
350 // void DestructEncoder()
351 // This function is called to delete the encoder instance, if possible, to
352 // have a fresh start. For codecs where encoder and decoder share the same
353 // instance we cannot delete the encoder and instead we will initialize the
354 // encoder. We also delete VAD and DTX if they have been created.
356 void DestructEncoder();
358 ///////////////////////////////////////////////////////////////////////////
359 // int16_t SamplesLeftToEncode()
360 // Returns the number of samples required to be able to do encoding.
363 // Number of samples.
365 int16_t SamplesLeftToEncode();
367 ///////////////////////////////////////////////////////////////////////////
369 // Set a unique ID for the codec to be used for tracing and debugging
372 // -id : A number to identify the codec.
374 void SetUniqueID(const uint32_t id);
376 ///////////////////////////////////////////////////////////////////////////
377 // UpdateDecoderSampFreq()
378 // For most of the codecs this function does nothing. It must be
379 // implemented for those codecs that one codec instance serves as the
380 // decoder for different flavors of the codec. One example is iSAC. there,
381 // iSAC 16 kHz and iSAC 32 kHz are treated as two different codecs with
382 // different payload types, however, there is only one iSAC instance to
383 // decode. The reason for that is we would like to decode and encode with
384 // the same codec instance for bandwidth estimator to work.
386 // Each time that we receive a new payload type, we call this function to
387 // prepare the decoder associated with the new payload. Normally, decoders
388 // doesn't have to do anything. For iSAC the decoder has to change it's
389 // sampling rate. The input parameter specifies the current flavor of the
390 // codec in codec database. For instance, if we just got a SWB payload then
391 // the input parameter is ACMCodecDB::isacswb.
394 // -codec_id : the ID of the codec associated with the
395 // payload type that we just received.
398 // 0 if succeeded in updating the decoder.
399 // -1 if failed to update.
401 virtual int16_t UpdateDecoderSampFreq(int16_t /* codec_id */) { return 0; }
403 ///////////////////////////////////////////////////////////////////////////
404 // UpdateEncoderSampFreq()
405 // Call this function to update the encoder sampling frequency. This
406 // is for codecs where one payload-name supports several encoder sampling
407 // frequencies. Otherwise, to change the sampling frequency we need to
408 // register new codec. ACM will consider that as registration of a new
409 // codec, not a change in parameter. For iSAC, switching from WB to SWB
410 // is treated as a change in parameter. Therefore, we need this function.
413 // -samp_freq_hz : encoder sampling frequency.
416 // -1 if failed, or if this is meaningless for the given codec.
419 virtual int16_t UpdateEncoderSampFreq(uint16_t samp_freq_hz)
420 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
422 ///////////////////////////////////////////////////////////////////////////
424 // Get the sampling frequency that the encoder (WebRtc wrapper) expects.
427 // -samp_freq_hz : sampling frequency, in Hertz, which the encoder
428 // should be fed with.
431 // -1 if failed to output sampling rate.
432 // 0 if the sample rate is returned successfully.
434 virtual int16_t EncoderSampFreq(uint16_t* samp_freq_hz)
435 SHARED_LOCKS_REQUIRED(codec_wrapper_lock_);
437 ///////////////////////////////////////////////////////////////////////////
438 // int32_t ConfigISACBandwidthEstimator()
439 // Call this function to configure the bandwidth estimator of ISAC.
440 // During the adaptation of bit-rate, iSAC automatically adjusts the
441 // frame-size (either 30 or 60 ms) to save on RTP header. The initial
442 // frame-size can be specified by the first argument. The configuration also
443 // regards the initial estimate of bandwidths. The estimator starts from
444 // this point and converges to the actual bottleneck. This is given by the
445 // second parameter. Furthermore, it is also possible to control the
446 // adaptation of frame-size. This is specified by the last parameter.
449 // -init_frame_fize_ms : initial frame-size in milliseconds. For iSAC-wb
450 // 30 ms and 60 ms (default) are acceptable values,
451 // and for iSAC-swb 30 ms is the only acceptable
452 // value. Zero indicates default value.
453 // -init_rate_bps : initial estimate of the bandwidth. Values
454 // between 10000 and 58000 are acceptable.
455 // -enforce_frame_size : if true, the frame-size will not be adapted.
458 // -1 if failed to configure the bandwidth estimator,
459 // 0 if the configuration was successfully applied.
461 virtual int32_t ConfigISACBandwidthEstimator(
462 const uint8_t init_frame_size_msec,
463 const uint16_t init_rate_bps,
464 const bool enforce_frame_size);
466 ///////////////////////////////////////////////////////////////////////////
467 // SetISACMaxPayloadSize()
468 // Set the maximum payload size of iSAC packets. No iSAC payload,
469 // regardless of its frame-size, may exceed the given limit. For
470 // an iSAC payload of size B bits and frame-size T sec we have;
471 // (B < max_payload_len_bytes * 8) and (B/T < max_rate_bit_per_sec), c.f.
475 // -max_payload_len_bytes : maximum payload size in bytes.
478 // -1 if failed to set the maximum payload-size.
479 // 0 if the given length is set successfully.
481 virtual int32_t SetISACMaxPayloadSize(const uint16_t max_payload_len_bytes);
483 ///////////////////////////////////////////////////////////////////////////
485 // Set the maximum instantaneous rate of iSAC. For a payload of B bits
486 // with a frame-size of T sec the instantaneous rate is B/T bits per
487 // second. Therefore, (B/T < max_rate_bit_per_sec) and
488 // (B < max_payload_len_bytes * 8) are always satisfied for iSAC payloads,
489 // c.f SetISACMaxPayloadSize().
492 // -max_rate_bps : maximum instantaneous bit-rate given in bits/sec.
495 // -1 if failed to set the maximum rate.
496 // 0 if the maximum rate is set successfully.
498 virtual int32_t SetISACMaxRate(const uint32_t max_rate_bps);
500 ///////////////////////////////////////////////////////////////////////////
502 // This is an iSAC-specific function. The function is called to get RED
503 // payload from a default-encoder.
506 // -isac_rate : the target rate of the main payload. A RED
507 // payload is generated according to the rate of
508 // main payload. Note that we are not specifying the
509 // rate of RED payload, but the main payload.
510 // -isac_bw_estimate : bandwidth information should be inserted in
514 // -payload : pointer to a buffer where the RED payload will
516 // -payload_len_bytes : a place-holder to write the length of the RED
520 // -1 if an error occurs, otherwise the length of the payload (in Bytes)
523 virtual int16_t REDPayloadISAC(const int32_t isac_rate,
524 const int16_t isac_bw_estimate,
526 int16_t* payload_len_bytes);
528 ///////////////////////////////////////////////////////////////////////////
529 // int SetOpusMaxPlaybackRate()
530 // Sets maximum playback rate the receiver will render, if the codec is Opus.
531 // This is to tell Opus that it is enough to code the input audio up to a
532 // bandwidth. Opus can take this information to optimize the bit rate and
533 // increase the computation efficiency.
536 // -frequency_hz : maximum playback rate in Hz.
539 // -1 if failed or on codecs other than Opus
542 virtual int SetOpusMaxPlaybackRate(int /* frequency_hz */);
544 ///////////////////////////////////////////////////////////////////////////
545 // HasFrameToEncode()
546 // Returns true if there is enough audio buffered for encoding, such that
547 // calling Encode() will return a payload.
549 bool HasFrameToEncode() const;
552 // Returns pointer to the AudioDecoder class of this codec. A codec which
553 // should own its own decoder (e.g. iSAC which need same instance for encoding
554 // and decoding, or a codec which should access decoder instance for specific
555 // decoder setting) should implement this method. This method is called if
556 // and only if the ACMCodecDB::codec_settings[codec_id].owns_decoder is true.
558 virtual AudioDecoder* Decoder(int /* codec_id */) { return NULL; }
560 ///////////////////////////////////////////////////////////////////////////
561 // bool HasInternalFEC()
562 // Used to check if the codec has internal FEC.
565 // true if the codec has an internal FEC, e.g. Opus.
568 bool HasInternalFEC() const {
569 ReadLockScoped rl(codec_wrapper_lock_);
570 return has_internal_fec_;
573 ///////////////////////////////////////////////////////////////////////////
575 // Sets the codec internal FEC. No effects on codecs that do not provide
579 // -enable_fec : if true FEC will be enabled otherwise the FEC is
583 // -1 if failed, or the codec does not support FEC
586 virtual int SetFEC(bool /* enable_fec */) { return -1; }
588 ///////////////////////////////////////////////////////////////////////////
589 // int SetPacketLossRate()
590 // Sets expected packet loss rate for encoding. Some encoders provide packet
591 // loss gnostic encoding to make stream less sensitive to packet losses,
592 // through e.g., FEC. No effects on codecs that do not provide such encoding.
595 // -loss_rate : expected packet loss rate (0 -- 100 inclusive).
599 // 0 if succeeded or packet loss rate is ignored.
601 virtual int SetPacketLossRate(int /* loss_rate */) { return 0; }
604 ///////////////////////////////////////////////////////////////////////////
605 // All the functions with FunctionNameSafe(...) contain the actual
606 // implementation of FunctionName(...). FunctionName() acquires an
607 // appropriate lock and calls FunctionNameSafe() to do the actual work.
608 // Therefore, for the description of functionality, input/output arguments
609 // and return value we refer to FunctionName()
612 ///////////////////////////////////////////////////////////////////////////
613 // See Add10MsSafe() for the description of function, input(s)/output(s)
616 virtual int32_t Add10MsDataSafe(const uint32_t timestamp,
618 const uint16_t length,
619 const uint8_t audio_channel)
620 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
622 ///////////////////////////////////////////////////////////////////////////
623 // See EncoderParam() for the description of function, input(s)/output(s)
626 int16_t EncoderParamsSafe(WebRtcACMCodecParams* enc_params)
627 SHARED_LOCKS_REQUIRED(codec_wrapper_lock_);
629 ///////////////////////////////////////////////////////////////////////////
630 // See ResetEncoder() for the description of function, input(s)/output(s)
633 int16_t ResetEncoderSafe() EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
635 ///////////////////////////////////////////////////////////////////////////
636 // See InitEncoder() for the description of function, input(s)/output(s)
639 int16_t InitEncoderSafe(WebRtcACMCodecParams* codec_params,
640 bool force_initialization)
641 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
643 ///////////////////////////////////////////////////////////////////////////
644 // See InitDecoder() for the description of function, input(s)/output(s)
647 int16_t InitDecoderSafe(WebRtcACMCodecParams* codec_params,
648 bool force_initialization);
650 ///////////////////////////////////////////////////////////////////////////
651 // See DestructEncoder() for the description of function,
652 // input(s)/output(s) and return value.
654 virtual void DestructEncoderSafe()
655 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_) = 0;
657 ///////////////////////////////////////////////////////////////////////////
658 // See SetBitRate() for the description of function, input(s)/output(s)
661 // Any codec that can change the bit-rate has to implement this.
663 virtual int16_t SetBitRateSafe(const int32_t bitrate_bps)
664 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
666 ///////////////////////////////////////////////////////////////////////////
667 // See GetEstimatedBandwidth() for the description of function,
668 // input(s)/output(s) and return value.
670 virtual int32_t GetEstimatedBandwidthSafe();
672 ///////////////////////////////////////////////////////////////////////////
673 // See SetEstimatedBandwidth() for the description of function,
674 // input(s)/output(s) and return value.
676 virtual int32_t SetEstimatedBandwidthSafe(int32_t estimated_bandwidth);
678 ///////////////////////////////////////////////////////////////////////////
679 // See GetRedPayload() for the description of function, input(s)/output(s)
682 virtual int32_t GetRedPayloadSafe(uint8_t* red_payload,
683 int16_t* payload_bytes);
685 ///////////////////////////////////////////////////////////////////////////
686 // See SetVAD() for the description of function, input(s)/output(s) and
689 int16_t SetVADSafe(bool* enable_dtx, bool* enable_vad, ACMVADMode* mode)
690 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
692 ///////////////////////////////////////////////////////////////////////////
693 // See ReplaceInternalDTX() for the description of function, input and
696 virtual int32_t ReplaceInternalDTXSafe(const bool replace_internal_dtx);
698 ///////////////////////////////////////////////////////////////////////////
699 // See IsInternalDTXReplaced() for the description of function, input and
702 virtual int32_t IsInternalDTXReplacedSafe(bool* internal_dtx_replaced);
704 ///////////////////////////////////////////////////////////////////////////
705 // int16_t CreateEncoder()
706 // Creates the encoder instance.
712 int16_t CreateEncoder() EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
714 ///////////////////////////////////////////////////////////////////////////
715 // int16_t EnableVAD();
716 // Enables VAD with the given mode. The VAD instance will be created if
717 // it does not exists.
720 // -mode : VAD mode c.f. audio_coding_module_typedefs.h for
727 int16_t EnableVAD(ACMVADMode mode)
728 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
730 ///////////////////////////////////////////////////////////////////////////
731 // int16_t DisableVAD()
738 int16_t DisableVAD() EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
740 ///////////////////////////////////////////////////////////////////////////
741 // int16_t EnableDTX()
742 // Enables DTX. This method should be overwritten for codecs which have
749 virtual int16_t EnableDTX() EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
751 ///////////////////////////////////////////////////////////////////////////
752 // int16_t DisableDTX()
753 // Disables usage of DTX. This method should be overwritten for codecs which
754 // have internal DTX.
760 virtual int16_t DisableDTX() EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
762 ///////////////////////////////////////////////////////////////////////////
763 // int16_t InternalEncode()
764 // This is a codec-specific function called in EncodeSafe() to actually
765 // encode a frame of audio.
768 // -bitstream : pointer to a buffer where the bit-stream is
770 // -bitstream_len_byte : the length of the bit-stream in bytes,
771 // a negative value indicates error.
775 // otherwise the length of the bit-stream is returned.
777 virtual int16_t InternalEncode(uint8_t* bitstream,
778 int16_t* bitstream_len_byte)
779 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_) = 0;
781 ///////////////////////////////////////////////////////////////////////////
782 // int16_t InternalInitEncoder()
783 // This is a codec-specific function called in InitEncoderSafe(), it has to
784 // do all codec-specific operation to initialize the encoder given the
785 // encoder parameters.
788 // -codec_params : pointer to a structure that contains parameters to
789 // initialize encoder.
790 // Set codec_params->codec_inst.rate to -1 for
791 // iSAC to operate in adaptive mode.
792 // (to do: if frame-length is -1 frame-length will be
793 // automatically adjusted, otherwise, given
794 // frame-length is forced)
800 virtual int16_t InternalInitEncoder(WebRtcACMCodecParams* codec_params)
801 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_) = 0;
803 ///////////////////////////////////////////////////////////////////////////
804 // void IncreaseNoMissedSamples()
805 // This method is called to increase the number of samples that are
806 // overwritten in the audio buffer.
809 // -num_samples : the number of overwritten samples is incremented
812 void IncreaseNoMissedSamples(const int16_t num_samples)
813 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
815 ///////////////////////////////////////////////////////////////////////////
816 // int16_t InternalCreateEncoder()
817 // This is a codec-specific method called in CreateEncoderSafe() it is
818 // supposed to perform all codec-specific operations to create encoder
825 virtual int16_t InternalCreateEncoder() = 0;
827 ///////////////////////////////////////////////////////////////////////////
828 // int16_t InternalResetEncoder()
829 // This method is called to reset the states of encoder. However, the
830 // current parameters, e.g. frame-length, should remain as they are. For
831 // most of the codecs a re-initialization of the encoder is what needs to
832 // be down. But for iSAC we like to keep the BWE history so we cannot
833 // re-initialize. As soon as such an API is implemented in iSAC this method
834 // has to be overwritten in ACMISAC class.
840 virtual int16_t InternalResetEncoder()
841 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
843 ///////////////////////////////////////////////////////////////////////////
844 // int16_t ProcessFrameVADDTX()
845 // This function is called when a full frame of audio is available. It will
846 // break the audio frame into blocks such that each block could be processed
847 // by VAD & CN/DTX. If a frame is divided into two blocks then there are two
848 // cases. First, the first block is active, the second block will not be
849 // processed by CN/DTX but only by VAD and return to caller with
850 // '*samples_processed' set to zero. There, the audio frame will be encoded
851 // by the encoder. Second, the first block is inactive and is processed by
852 // CN/DTX, then we stop processing the next block and return to the caller
853 // which is EncodeSafe(), with "*samples_processed" equal to the number of
854 // samples in first block.
857 // -bitstream : pointer to a buffer where DTX frame, if
858 // generated, will be written to.
859 // -bitstream_len_byte : contains the length of bit-stream in bytes, if
860 // generated. Zero if no bit-stream is generated.
861 // -samples_processed : contains no of samples that actually CN has
862 // processed. Those samples processed by CN will not
863 // be encoded by the encoder, obviously. If
864 // contains zero, it means that the frame has been
865 // identified as active by VAD. Note that
866 // "*samples_processed" might be non-zero but
867 // "*bitstream_len_byte" be zero.
873 int16_t ProcessFrameVADDTX(uint8_t* bitstream,
874 int16_t* bitstream_len_byte,
875 int16_t* samples_processed)
876 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_);
878 ///////////////////////////////////////////////////////////////////////////
880 // Call to get the current encoding rate of the encoder. This function
881 // should be overwritten for codecs which automatically change their
882 // target rate. One example is iSAC. The output of the function is the
883 // current target rate.
886 // -rate_bps : the current target rate of the codec.
888 virtual void CurrentRate(int32_t* /* rate_bps */) {}
890 // &in_audio_[in_audio_ix_write_] always point to where new audio can be
892 int16_t in_audio_ix_write_ GUARDED_BY(codec_wrapper_lock_);
894 // &in_audio_[in_audio_ix_read_] points to where audio has to be read from
895 int16_t in_audio_ix_read_ GUARDED_BY(codec_wrapper_lock_);
897 int16_t in_timestamp_ix_write_ GUARDED_BY(codec_wrapper_lock_);
899 // Where the audio is stored before encoding,
900 // To save memory the following buffer can be allocated
901 // dynamically for 80 ms depending on the sampling frequency
903 int16_t* in_audio_ GUARDED_BY(codec_wrapper_lock_);
904 uint32_t* in_timestamp_ GUARDED_BY(codec_wrapper_lock_);
906 int16_t frame_len_smpl_ GUARDED_BY(codec_wrapper_lock_);
907 uint16_t num_channels_ GUARDED_BY(codec_wrapper_lock_);
909 // This will point to a static database of the supported codecs
910 int16_t codec_id_ GUARDED_BY(codec_wrapper_lock_);
912 // This will account for the number of samples were not encoded
913 // the case is rare, either samples are missed due to overwrite
914 // at input buffer or due to encoding error
915 uint32_t num_missed_samples_ GUARDED_BY(codec_wrapper_lock_);
917 // True if the encoder instance created
918 bool encoder_exist_ GUARDED_BY(codec_wrapper_lock_);
920 // True if the encoder instance initialized
921 bool encoder_initialized_ GUARDED_BY(codec_wrapper_lock_);
923 const bool registered_in_neteq_
924 GUARDED_BY(codec_wrapper_lock_); // TODO(henrik.lundin) Remove?
927 bool has_internal_dtx_ GUARDED_BY(codec_wrapper_lock_);
928 WebRtcVadInst* ptr_vad_inst_ GUARDED_BY(codec_wrapper_lock_);
929 bool vad_enabled_ GUARDED_BY(codec_wrapper_lock_);
930 ACMVADMode vad_mode_ GUARDED_BY(codec_wrapper_lock_);
931 int16_t vad_label_[MAX_FRAME_SIZE_10MSEC] GUARDED_BY(codec_wrapper_lock_);
932 bool dtx_enabled_ GUARDED_BY(codec_wrapper_lock_);
933 WebRtcCngEncInst* ptr_dtx_inst_ GUARDED_BY(codec_wrapper_lock_);
934 uint8_t num_lpc_params_ // TODO(henrik.lundin) Delete and
935 GUARDED_BY(codec_wrapper_lock_); // replace with kNewCNGNumLPCParams.
936 bool sent_cn_previous_ GUARDED_BY(codec_wrapper_lock_);
937 int16_t prev_frame_cng_ GUARDED_BY(codec_wrapper_lock_);
940 bool has_internal_fec_ GUARDED_BY(codec_wrapper_lock_);
942 WebRtcACMCodecParams encoder_params_ GUARDED_BY(codec_wrapper_lock_);
944 // Used to lock wrapper internal data
945 // such as buffers and state variables.
946 RWLockWrapper& codec_wrapper_lock_;
948 uint32_t last_timestamp_ GUARDED_BY(codec_wrapper_lock_);
954 } // namespace webrtc
956 #endif // WEBRTC_MODULES_AUDIO_CODING_MAIN_ACM2_ACM_GENERIC_CODEC_H_