1 /* 2 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved. 3 * 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. 9 */ 10 11 #ifndef WEBRTC_MODULES_AUDIO_CODING_MAIN_ACM2_ACM_GENERIC_CODEC_H_ 12 #define WEBRTC_MODULES_AUDIO_CODING_MAIN_ACM2_ACM_GENERIC_CODEC_H_ 13 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" 21 22 #define MAX_FRAME_SIZE_10MSEC 6 23 24 // forward declaration 25 struct WebRtcVadInst; 26 struct WebRtcCngEncInst; 27 28 namespace webrtc { 29 30 struct WebRtcACMCodecParams; 31 struct CodecInst; 32 33 namespace acm2 { 34 35 // forward declaration 36 class AcmReceiver; 37 38 class ACMGenericCodec { 39 public: 40 /////////////////////////////////////////////////////////////////////////// 41 // Constructor of the class 42 // 43 ACMGenericCodec(); 44 45 /////////////////////////////////////////////////////////////////////////// 46 // Destructor of the class. 47 // 48 virtual ~ACMGenericCodec(); 49 50 /////////////////////////////////////////////////////////////////////////// 51 // ACMGenericCodec* CreateInstance(); 52 // The function will be used for FEC. It is not implemented yet. 53 // 54 virtual ACMGenericCodec* CreateInstance() = 0; 55 56 /////////////////////////////////////////////////////////////////////////// 57 // int16_t Encode() 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. 62 // 63 // A) Neither VAD nor DTX is active; the frame is encoded by the encoder. 64 // 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. 69 // 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. 74 // 75 // This function acquires the appropriate locks and calls EncodeSafe() for 76 // the actual processing. 77 // 78 // Outputs: 79 // -bitstream : a buffer where bit-stream will be written to. 80 // -bitstream_len_byte : contains the length of the bit-stream in 81 // bytes. 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) 88 // -kNoEncoding: 89 // there was not enough data to encode. or 90 // some error has happened that we could 91 // not do encoding. 92 // -kActiveNormalEncoded: 93 // the audio frame is active and encoded by 94 // the given codec. 95 // -kPassiveNormalEncoded: 96 // the audio frame is passive but coded with 97 // the given codec (NO DTX). 98 // -kPassiveDTXWB: 99 // The audio frame is passive and used 100 // wide-band CN to encode. 101 // -kPassiveDTXNB: 102 // The audio frame is passive and used 103 // narrow-band CN to encode. 104 // 105 // Return value: 106 // -1 if error is occurred, otherwise the length of the bit-stream in 107 // bytes. 108 // 109 int16_t Encode(uint8_t* bitstream, 110 int16_t* bitstream_len_byte, 111 uint32_t* timestamp, 112 WebRtcACMEncodingType* encoding_type); 113 114 /////////////////////////////////////////////////////////////////////////// 115 // bool EncoderInitialized(); 116 // 117 // Return value: 118 // True if the encoder is successfully initialized, 119 // false otherwise. 120 // 121 bool EncoderInitialized(); 122 123 /////////////////////////////////////////////////////////////////////////// 124 // int16_t EncoderParams() 125 // It is called to get encoder parameters. It will call 126 // EncoderParamsSafe() in turn. 127 // 128 // Output: 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 132 // invalid values 133 // Return value: 134 // -1 if the encoder is not initialized, 135 // 0 otherwise. 136 // 137 int16_t EncoderParams(WebRtcACMCodecParams* enc_params); 138 139 /////////////////////////////////////////////////////////////////////////// 140 // int16_t InitEncoder(...) 141 // This function is called to initialize the encoder with the given 142 // parameters. 143 // 144 // Input: 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. 149 // 150 // Return value: 151 // 0 if could initialize successfully, 152 // -1 if failed to initialize. 153 // 154 // 155 int16_t InitEncoder(WebRtcACMCodecParams* codec_params, 156 bool force_initialization); 157 158 /////////////////////////////////////////////////////////////////////////// 159 // int32_t Add10MsData(...) 160 // This function is called to add 10 ms of audio to the audio buffer of 161 // the codec. 162 // 163 // Inputs: 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 169 // frequency 170 // -length : the length of the audio buffer 171 // -audio_channel : 0 for mono, 1 for stereo (not supported yet) 172 // 173 // Return values: 174 // -1 if failed 175 // 0 otherwise. 176 // 177 int32_t Add10MsData(const uint32_t timestamp, 178 const int16_t* data, 179 const uint16_t length, 180 const uint8_t audio_channel); 181 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) 188 // 189 // Return Value: 190 // Number of samples which are overwritten. 191 // 192 uint32_t NoMissedSamples() const; 193 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()) 198 // 199 void ResetNoMissedSamples(); 200 201 /////////////////////////////////////////////////////////////////////////// 202 // int16_t SetBitRate() 203 // The function is called to set the encoding rate. 204 // 205 // Input: 206 // -bitrate_bps : encoding rate in bits per second 207 // 208 // Return value: 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 212 // 213 int16_t SetBitRate(const int32_t bitrate_bps); 214 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. 219 // 220 // Return value: 221 // timestamp of the first 10 ms audio in the audio buffer. 222 // 223 uint32_t EarliestTimestamp() const; 224 225 /////////////////////////////////////////////////////////////////////////// 226 // int16_t SetVAD() 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 234 // are kept. 235 // 236 // Inputs/Output: 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 245 // |enable_vad|. 246 // -mode : this specifies the aggressiveness of VAD. 247 // 248 // Return value 249 // -1 if failed to set DTX & VAD as specified, 250 // 0 if succeeded. 251 // 252 int16_t SetVAD(bool* enable_dtx, bool* enable_vad, ACMVADMode* mode); 253 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. 259 // 260 // Input: 261 // -replace_internal_dtx : if true the internal DTX is replaced with WebRtc. 262 // 263 // Return value 264 // -1 if failed to replace internal DTX, 265 // 0 if succeeded. 266 // 267 int32_t ReplaceInternalDTX(const bool replace_internal_dtx); 268 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. 274 // 275 // Output: 276 // -internal_dtx_replaced: if true the internal DTX is replaced with WebRtc. 277 // 278 // Return value 279 // -1 if failed to check 280 // 0 if succeeded. 281 // 282 int32_t IsInternalDTXReplaced(bool* internal_dtx_replaced); 283 284 /////////////////////////////////////////////////////////////////////////// 285 // bool HasInternalDTX() 286 // Used to check if the codec has internal DTX. 287 // 288 // Return value: 289 // true if the codec has an internal DTX, e.g. G729, 290 // false otherwise. 291 // 292 bool HasInternalDTX() const { 293 ReadLockScoped rl(codec_wrapper_lock_); 294 return has_internal_dtx_; 295 } 296 297 /////////////////////////////////////////////////////////////////////////// 298 // int32_t GetEstimatedBandwidth() 299 // Used to get decoder estimated bandwidth. Only iSAC will provide a value. 300 // 301 // 302 // Return value: 303 // -1 if fails to get decoder estimated bandwidth, 304 // >0 estimated bandwidth in bits/sec. 305 // 306 int32_t GetEstimatedBandwidth(); 307 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. 312 // 313 // Input: 314 // -estimated_bandwidth: estimated bandwidth in bits/sec 315 // 316 // Return value: 317 // -1 if fails to set estimated bandwidth, 318 // 0 on success. 319 // 320 int32_t SetEstimatedBandwidth(int32_t estimated_bandwidth); 321 322 /////////////////////////////////////////////////////////////////////////// 323 // int32_t GetRedPayload() 324 // Used to get codec specific RED payload (if such is implemented). 325 // Currently only done in iSAC. 326 // 327 // Outputs: 328 // -red_payload : a pointer to the data for RED payload. 329 // -payload_bytes : number of bytes in RED payload. 330 // 331 // Return value: 332 // -1 if fails to get codec specific RED, 333 // 0 if succeeded. 334 // 335 int32_t GetRedPayload(uint8_t* red_payload, int16_t* payload_bytes); 336 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.) 342 // 343 // Return value 344 // -1 if failed, 345 // 0 if succeeded. 346 // 347 int16_t ResetEncoder(); 348 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. 355 // 356 void DestructEncoder(); 357 358 /////////////////////////////////////////////////////////////////////////// 359 // int16_t SamplesLeftToEncode() 360 // Returns the number of samples required to be able to do encoding. 361 // 362 // Return value: 363 // Number of samples. 364 // 365 int16_t SamplesLeftToEncode(); 366 367 /////////////////////////////////////////////////////////////////////////// 368 // SetUniqueID() 369 // Set a unique ID for the codec to be used for tracing and debugging 370 // 371 // Input 372 // -id : A number to identify the codec. 373 // 374 void SetUniqueID(const uint32_t id); 375 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. 385 // 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. 392 // 393 // Input: 394 // -codec_id : the ID of the codec associated with the 395 // payload type that we just received. 396 // 397 // Return value: 398 // 0 if succeeded in updating the decoder. 399 // -1 if failed to update. 400 // 401 virtual int16_t UpdateDecoderSampFreq(int16_t /* codec_id */) { return 0; } 402 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. 411 // 412 // Input: 413 // -samp_freq_hz : encoder sampling frequency. 414 // 415 // Return value: 416 // -1 if failed, or if this is meaningless for the given codec. 417 // 0 if succeeded. 418 // 419 virtual int16_t UpdateEncoderSampFreq(uint16_t samp_freq_hz) 420 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 421 422 /////////////////////////////////////////////////////////////////////////// 423 // EncoderSampFreq() 424 // Get the sampling frequency that the encoder (WebRtc wrapper) expects. 425 // 426 // Output: 427 // -samp_freq_hz : sampling frequency, in Hertz, which the encoder 428 // should be fed with. 429 // 430 // Return value: 431 // -1 if failed to output sampling rate. 432 // 0 if the sample rate is returned successfully. 433 // 434 virtual int16_t EncoderSampFreq(uint16_t* samp_freq_hz) 435 SHARED_LOCKS_REQUIRED(codec_wrapper_lock_); 436 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. 447 // 448 // Input: 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. 456 // 457 // Return value: 458 // -1 if failed to configure the bandwidth estimator, 459 // 0 if the configuration was successfully applied. 460 // 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); 465 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. 472 // SetISACMaxRate(). 473 // 474 // Input: 475 // -max_payload_len_bytes : maximum payload size in bytes. 476 // 477 // Return value: 478 // -1 if failed to set the maximum payload-size. 479 // 0 if the given length is set successfully. 480 // 481 virtual int32_t SetISACMaxPayloadSize(const uint16_t max_payload_len_bytes); 482 483 /////////////////////////////////////////////////////////////////////////// 484 // SetISACMaxRate() 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(). 490 // 491 // Input: 492 // -max_rate_bps : maximum instantaneous bit-rate given in bits/sec. 493 // 494 // Return value: 495 // -1 if failed to set the maximum rate. 496 // 0 if the maximum rate is set successfully. 497 // 498 virtual int32_t SetISACMaxRate(const uint32_t max_rate_bps); 499 500 /////////////////////////////////////////////////////////////////////////// 501 // REDPayloadISAC() 502 // This is an iSAC-specific function. The function is called to get RED 503 // payload from a default-encoder. 504 // 505 // Inputs: 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 511 // RED payload. 512 // 513 // Output: 514 // -payload : pointer to a buffer where the RED payload will 515 // written to. 516 // -payload_len_bytes : a place-holder to write the length of the RED 517 // payload in Bytes. 518 // 519 // Return value: 520 // -1 if an error occurs, otherwise the length of the payload (in Bytes) 521 // is returned. 522 // 523 virtual int16_t REDPayloadISAC(const int32_t isac_rate, 524 const int16_t isac_bw_estimate, 525 uint8_t* payload, 526 int16_t* payload_len_bytes); 527 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. 534 // 535 // Input: 536 // -frequency_hz : maximum playback rate in Hz. 537 // 538 // Return value: 539 // -1 if failed or on codecs other than Opus 540 // 0 if succeeded. 541 // 542 virtual int SetOpusMaxPlaybackRate(int /* frequency_hz */); 543 544 /////////////////////////////////////////////////////////////////////////// 545 // HasFrameToEncode() 546 // Returns true if there is enough audio buffered for encoding, such that 547 // calling Encode() will return a payload. 548 // 549 bool HasFrameToEncode() const; 550 551 // 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. 557 // 558 virtual AudioDecoder* Decoder(int /* codec_id */) { return NULL; } 559 560 /////////////////////////////////////////////////////////////////////////// 561 // bool HasInternalFEC() 562 // Used to check if the codec has internal FEC. 563 // 564 // Return value: 565 // true if the codec has an internal FEC, e.g. Opus. 566 // false otherwise. 567 // 568 bool HasInternalFEC() const { 569 ReadLockScoped rl(codec_wrapper_lock_); 570 return has_internal_fec_; 571 } 572 573 /////////////////////////////////////////////////////////////////////////// 574 // int SetFEC(); 575 // Sets the codec internal FEC. No effects on codecs that do not provide 576 // internal FEC. 577 // 578 // Input: 579 // -enable_fec : if true FEC will be enabled otherwise the FEC is 580 // disabled. 581 // 582 // Return value: 583 // -1 if failed, or the codec does not support FEC 584 // 0 if succeeded. 585 // 586 virtual int SetFEC(bool /* enable_fec */) { return -1; } 587 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. 593 // 594 // Input: 595 // -loss_rate : expected packet loss rate (0 -- 100 inclusive). 596 // 597 // Return value: 598 // -1 if failed, 599 // 0 if succeeded or packet loss rate is ignored. 600 // 601 virtual int SetPacketLossRate(int /* loss_rate */) { return 0; } 602 603 protected: 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() 610 // 611 612 /////////////////////////////////////////////////////////////////////////// 613 // See Add10MsSafe() for the description of function, input(s)/output(s) 614 // and return value. 615 // 616 virtual int32_t Add10MsDataSafe(const uint32_t timestamp, 617 const int16_t* data, 618 const uint16_t length, 619 const uint8_t audio_channel) 620 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 621 622 /////////////////////////////////////////////////////////////////////////// 623 // See EncoderParam() for the description of function, input(s)/output(s) 624 // and return value. 625 // 626 int16_t EncoderParamsSafe(WebRtcACMCodecParams* enc_params) 627 SHARED_LOCKS_REQUIRED(codec_wrapper_lock_); 628 629 /////////////////////////////////////////////////////////////////////////// 630 // See ResetEncoder() for the description of function, input(s)/output(s) 631 // and return value. 632 // 633 int16_t ResetEncoderSafe() EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 634 635 /////////////////////////////////////////////////////////////////////////// 636 // See InitEncoder() for the description of function, input(s)/output(s) 637 // and return value. 638 // 639 int16_t InitEncoderSafe(WebRtcACMCodecParams* codec_params, 640 bool force_initialization) 641 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 642 643 /////////////////////////////////////////////////////////////////////////// 644 // See InitDecoder() for the description of function, input(s)/output(s) 645 // and return value. 646 // 647 int16_t InitDecoderSafe(WebRtcACMCodecParams* codec_params, 648 bool force_initialization); 649 650 /////////////////////////////////////////////////////////////////////////// 651 // See DestructEncoder() for the description of function, 652 // input(s)/output(s) and return value. 653 // 654 virtual void DestructEncoderSafe() 655 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_) = 0; 656 657 /////////////////////////////////////////////////////////////////////////// 658 // See SetBitRate() for the description of function, input(s)/output(s) 659 // and return value. 660 // 661 // Any codec that can change the bit-rate has to implement this. 662 // 663 virtual int16_t SetBitRateSafe(const int32_t bitrate_bps) 664 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 665 666 /////////////////////////////////////////////////////////////////////////// 667 // See GetEstimatedBandwidth() for the description of function, 668 // input(s)/output(s) and return value. 669 // 670 virtual int32_t GetEstimatedBandwidthSafe(); 671 672 /////////////////////////////////////////////////////////////////////////// 673 // See SetEstimatedBandwidth() for the description of function, 674 // input(s)/output(s) and return value. 675 // 676 virtual int32_t SetEstimatedBandwidthSafe(int32_t estimated_bandwidth); 677 678 /////////////////////////////////////////////////////////////////////////// 679 // See GetRedPayload() for the description of function, input(s)/output(s) 680 // and return value. 681 // 682 virtual int32_t GetRedPayloadSafe(uint8_t* red_payload, 683 int16_t* payload_bytes); 684 685 /////////////////////////////////////////////////////////////////////////// 686 // See SetVAD() for the description of function, input(s)/output(s) and 687 // return value. 688 // 689 int16_t SetVADSafe(bool* enable_dtx, bool* enable_vad, ACMVADMode* mode) 690 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 691 692 /////////////////////////////////////////////////////////////////////////// 693 // See ReplaceInternalDTX() for the description of function, input and 694 // return value. 695 // 696 virtual int32_t ReplaceInternalDTXSafe(const bool replace_internal_dtx); 697 698 /////////////////////////////////////////////////////////////////////////// 699 // See IsInternalDTXReplaced() for the description of function, input and 700 // return value. 701 // 702 virtual int32_t IsInternalDTXReplacedSafe(bool* internal_dtx_replaced); 703 704 /////////////////////////////////////////////////////////////////////////// 705 // int16_t CreateEncoder() 706 // Creates the encoder instance. 707 // 708 // Return value: 709 // -1 if failed, 710 // 0 if succeeded. 711 // 712 int16_t CreateEncoder() EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 713 714 /////////////////////////////////////////////////////////////////////////// 715 // int16_t EnableVAD(); 716 // Enables VAD with the given mode. The VAD instance will be created if 717 // it does not exists. 718 // 719 // Input: 720 // -mode : VAD mode c.f. audio_coding_module_typedefs.h for 721 // the options. 722 // 723 // Return value: 724 // -1 if failed, 725 // 0 if succeeded. 726 // 727 int16_t EnableVAD(ACMVADMode mode) 728 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 729 730 /////////////////////////////////////////////////////////////////////////// 731 // int16_t DisableVAD() 732 // Disables VAD. 733 // 734 // Return value: 735 // -1 if failed, 736 // 0 if succeeded. 737 // 738 int16_t DisableVAD() EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 739 740 /////////////////////////////////////////////////////////////////////////// 741 // int16_t EnableDTX() 742 // Enables DTX. This method should be overwritten for codecs which have 743 // internal DTX. 744 // 745 // Return value: 746 // -1 if failed, 747 // 0 if succeeded. 748 // 749 virtual int16_t EnableDTX() EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 750 751 /////////////////////////////////////////////////////////////////////////// 752 // int16_t DisableDTX() 753 // Disables usage of DTX. This method should be overwritten for codecs which 754 // have internal DTX. 755 // 756 // Return value: 757 // -1 if failed, 758 // 0 if succeeded. 759 // 760 virtual int16_t DisableDTX() EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 761 762 /////////////////////////////////////////////////////////////////////////// 763 // int16_t InternalEncode() 764 // This is a codec-specific function called in EncodeSafe() to actually 765 // encode a frame of audio. 766 // 767 // Outputs: 768 // -bitstream : pointer to a buffer where the bit-stream is 769 // written to. 770 // -bitstream_len_byte : the length of the bit-stream in bytes, 771 // a negative value indicates error. 772 // 773 // Return value: 774 // -1 if failed, 775 // otherwise the length of the bit-stream is returned. 776 // 777 virtual int16_t InternalEncode(uint8_t* bitstream, 778 int16_t* bitstream_len_byte) 779 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_) = 0; 780 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. 786 // 787 // Input: 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) 795 // 796 // Return value: 797 // -1 if failed, 798 // 0 if succeeded. 799 // 800 virtual int16_t InternalInitEncoder(WebRtcACMCodecParams* codec_params) 801 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_) = 0; 802 803 /////////////////////////////////////////////////////////////////////////// 804 // void IncreaseNoMissedSamples() 805 // This method is called to increase the number of samples that are 806 // overwritten in the audio buffer. 807 // 808 // Input: 809 // -num_samples : the number of overwritten samples is incremented 810 // by this value. 811 // 812 void IncreaseNoMissedSamples(const int16_t num_samples) 813 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 814 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 819 // instance. 820 // 821 // Return value: 822 // -1 if failed, 823 // 0 if succeeded. 824 // 825 virtual int16_t InternalCreateEncoder() = 0; 826 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. 835 // 836 // Return value: 837 // -1 if failed, 838 // 0 if succeeded. 839 // 840 virtual int16_t InternalResetEncoder() 841 EXCLUSIVE_LOCKS_REQUIRED(codec_wrapper_lock_); 842 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. 855 // 856 // Output: 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. 868 // 869 // Return value: 870 // -1 if failed, 871 // 0 if succeeded. 872 // 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_); 877 878 /////////////////////////////////////////////////////////////////////////// 879 // CurrentRate() 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. 884 // 885 // Output: 886 // -rate_bps : the current target rate of the codec. 887 // 888 virtual void CurrentRate(int32_t* /* rate_bps */) {} 889 890 // &in_audio_[in_audio_ix_write_] always point to where new audio can be 891 // written to 892 int16_t in_audio_ix_write_ GUARDED_BY(codec_wrapper_lock_); 893 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_); 896 897 int16_t in_timestamp_ix_write_ GUARDED_BY(codec_wrapper_lock_); 898 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 902 // of the codec. 903 int16_t* in_audio_ GUARDED_BY(codec_wrapper_lock_); 904 uint32_t* in_timestamp_ GUARDED_BY(codec_wrapper_lock_); 905 906 int16_t frame_len_smpl_ GUARDED_BY(codec_wrapper_lock_); 907 uint16_t num_channels_ GUARDED_BY(codec_wrapper_lock_); 908 909 // This will point to a static database of the supported codecs 910 int16_t codec_id_ GUARDED_BY(codec_wrapper_lock_); 911 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_); 916 917 // True if the encoder instance created 918 bool encoder_exist_ GUARDED_BY(codec_wrapper_lock_); 919 920 // True if the encoder instance initialized 921 bool encoder_initialized_ GUARDED_BY(codec_wrapper_lock_); 922 923 const bool registered_in_neteq_ 924 GUARDED_BY(codec_wrapper_lock_); // TODO(henrik.lundin) Remove? 925 926 // VAD/DTX 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_); 938 939 // FEC. 940 bool has_internal_fec_ GUARDED_BY(codec_wrapper_lock_); 941 942 WebRtcACMCodecParams encoder_params_ GUARDED_BY(codec_wrapper_lock_); 943 944 // Used to lock wrapper internal data 945 // such as buffers and state variables. 946 RWLockWrapper& codec_wrapper_lock_; 947 948 uint32_t last_timestamp_ GUARDED_BY(codec_wrapper_lock_); 949 uint32_t unique_id_; 950 }; 951 952 } // namespace acm2 953 954 } // namespace webrtc 955 956 #endif // WEBRTC_MODULES_AUDIO_CODING_MAIN_ACM2_ACM_GENERIC_CODEC_H_ 957