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_INTERFACE_AUDIO_CODING_MODULE_H_ 12 #define WEBRTC_MODULES_AUDIO_CODING_MAIN_INTERFACE_AUDIO_CODING_MODULE_H_ 13 14 #include <vector> 15 16 #include "webrtc/common_types.h" 17 #include "webrtc/modules/audio_coding/main/interface/audio_coding_module_typedefs.h" 18 #include "webrtc/modules/audio_coding/neteq/interface/neteq.h" 19 #include "webrtc/modules/interface/module.h" 20 #include "webrtc/system_wrappers/interface/clock.h" 21 #include "webrtc/typedefs.h" 22 23 namespace webrtc { 24 25 // forward declarations 26 struct CodecInst; 27 struct WebRtcRTPHeader; 28 class AudioFrame; 29 class RTPFragmentationHeader; 30 31 #define WEBRTC_10MS_PCM_AUDIO 960 // 16 bits super wideband 48 kHz 32 33 // Callback class used for sending data ready to be packetized 34 class AudioPacketizationCallback { 35 public: 36 virtual ~AudioPacketizationCallback() {} 37 38 virtual int32_t SendData( 39 FrameType frame_type, 40 uint8_t payload_type, 41 uint32_t timestamp, 42 const uint8_t* payload_data, 43 uint16_t payload_len_bytes, 44 const RTPFragmentationHeader* fragmentation) = 0; 45 }; 46 47 // Callback class used for inband Dtmf detection 48 class AudioCodingFeedback { 49 public: 50 virtual ~AudioCodingFeedback() {} 51 52 virtual int32_t IncomingDtmf(const uint8_t digit_dtmf, 53 const bool end) = 0; 54 }; 55 56 // Callback class used for reporting VAD decision 57 class ACMVADCallback { 58 public: 59 virtual ~ACMVADCallback() {} 60 61 virtual int32_t InFrameType(int16_t frameType) = 0; 62 }; 63 64 // Callback class used for reporting receiver statistics 65 class ACMVQMonCallback { 66 public: 67 virtual ~ACMVQMonCallback() {} 68 69 virtual int32_t NetEqStatistics( 70 const int32_t id, // current ACM id 71 const uint16_t MIUsValid, // valid voice duration in ms 72 const uint16_t MIUsReplaced, // concealed voice duration in ms 73 const uint8_t eventFlags, // concealed voice flags 74 const uint16_t delayMS) = 0; // average delay in ms 75 }; 76 77 class AudioCodingModule: public Module { 78 protected: 79 AudioCodingModule() {} 80 81 public: 82 struct Config { 83 Config() 84 : id(0), 85 neteq_config(), 86 clock(Clock::GetRealTimeClock()) {} 87 88 int id; 89 NetEq::Config neteq_config; 90 Clock* clock; 91 }; 92 93 /////////////////////////////////////////////////////////////////////////// 94 // Creation and destruction of a ACM. 95 // 96 // The second method is used for testing where a simulated clock can be 97 // injected into ACM. ACM will take the ownership of the object clock and 98 // delete it when destroyed. 99 // 100 static AudioCodingModule* Create(int id); 101 static AudioCodingModule* Create(int id, Clock* clock); 102 virtual ~AudioCodingModule() {}; 103 104 /////////////////////////////////////////////////////////////////////////// 105 // Utility functions 106 // 107 108 /////////////////////////////////////////////////////////////////////////// 109 // uint8_t NumberOfCodecs() 110 // Returns number of supported codecs. 111 // 112 // Return value: 113 // number of supported codecs. 114 /// 115 static int NumberOfCodecs(); 116 117 /////////////////////////////////////////////////////////////////////////// 118 // int32_t Codec() 119 // Get supported codec with list number. 120 // 121 // Input: 122 // -list_id : list number. 123 // 124 // Output: 125 // -codec : a structure where the parameters of the codec, 126 // given by list number is written to. 127 // 128 // Return value: 129 // -1 if the list number (list_id) is invalid. 130 // 0 if succeeded. 131 // 132 static int Codec(int list_id, CodecInst* codec); 133 134 /////////////////////////////////////////////////////////////////////////// 135 // int32_t Codec() 136 // Get supported codec with the given codec name, sampling frequency, and 137 // a given number of channels. 138 // 139 // Input: 140 // -payload_name : name of the codec. 141 // -sampling_freq_hz : sampling frequency of the codec. Note! for RED 142 // a sampling frequency of -1 is a valid input. 143 // -channels : number of channels ( 1 - mono, 2 - stereo). 144 // 145 // Output: 146 // -codec : a structure where the function returns the 147 // default parameters of the codec. 148 // 149 // Return value: 150 // -1 if no codec matches the given parameters. 151 // 0 if succeeded. 152 // 153 static int Codec(const char* payload_name, CodecInst* codec, 154 int sampling_freq_hz, int channels); 155 156 /////////////////////////////////////////////////////////////////////////// 157 // int32_t Codec() 158 // 159 // Returns the list number of the given codec name, sampling frequency, and 160 // a given number of channels. 161 // 162 // Input: 163 // -payload_name : name of the codec. 164 // -sampling_freq_hz : sampling frequency of the codec. Note! for RED 165 // a sampling frequency of -1 is a valid input. 166 // -channels : number of channels ( 1 - mono, 2 - stereo). 167 // 168 // Return value: 169 // if the codec is found, the index of the codec in the list, 170 // -1 if the codec is not found. 171 // 172 static int Codec(const char* payload_name, int sampling_freq_hz, 173 int channels); 174 175 /////////////////////////////////////////////////////////////////////////// 176 // bool IsCodecValid() 177 // Checks the validity of the parameters of the given codec. 178 // 179 // Input: 180 // -codec : the structure which keeps the parameters of the 181 // codec. 182 // 183 // Return value: 184 // true if the parameters are valid, 185 // false if any parameter is not valid. 186 // 187 static bool IsCodecValid(const CodecInst& codec); 188 189 /////////////////////////////////////////////////////////////////////////// 190 // Sender 191 // 192 193 /////////////////////////////////////////////////////////////////////////// 194 // int32_t InitializeSender() 195 // Any encoder-related state of ACM will be initialized to the 196 // same state when ACM is created. This will not interrupt or 197 // effect decoding functionality of ACM. ACM will lose all the 198 // encoding-related settings by calling this function. 199 // For instance, a send codec has to be registered again. 200 // 201 // Return value: 202 // -1 if failed to initialize, 203 // 0 if succeeded. 204 // 205 virtual int32_t InitializeSender() = 0; 206 207 /////////////////////////////////////////////////////////////////////////// 208 // int32_t ResetEncoder() 209 // This API resets the states of encoder. All the encoder settings, such as 210 // send-codec or VAD/DTX, will be preserved. 211 // 212 // Return value: 213 // -1 if failed to initialize, 214 // 0 if succeeded. 215 // 216 virtual int32_t ResetEncoder() = 0; 217 218 /////////////////////////////////////////////////////////////////////////// 219 // int32_t RegisterSendCodec() 220 // Registers a codec, specified by |send_codec|, as sending codec. 221 // This API can be called multiple of times to register Codec. The last codec 222 // registered overwrites the previous ones. 223 // The API can also be used to change payload type for CNG and RED, which are 224 // registered by default to default payload types. 225 // Note that registering CNG and RED won't overwrite speech codecs. 226 // This API can be called to set/change the send payload-type, frame-size 227 // or encoding rate (if applicable for the codec). 228 // 229 // Note: If a stereo codec is registered as send codec, VAD/DTX will 230 // automatically be turned off, since it is not supported for stereo sending. 231 // 232 // Note: If a secondary encoder is already registered, and the new send-codec 233 // has a sampling rate that does not match the secondary encoder, the 234 // secondary encoder will be unregistered. 235 // 236 // Input: 237 // -send_codec : Parameters of the codec to be registered, c.f. 238 // common_types.h for the definition of 239 // CodecInst. 240 // 241 // Return value: 242 // -1 if failed to initialize, 243 // 0 if succeeded. 244 // 245 virtual int32_t RegisterSendCodec(const CodecInst& send_codec) = 0; 246 247 /////////////////////////////////////////////////////////////////////////// 248 // int RegisterSecondarySendCodec() 249 // Register a secondary encoder to enable dual-streaming. If a secondary 250 // codec is already registered, it will be removed before the new one is 251 // registered. 252 // 253 // Note: The secondary encoder will be unregistered if a primary codec 254 // is set with a sampling rate which does not match that of the existing 255 // secondary codec. 256 // 257 // Input: 258 // -send_codec : Parameters of the codec to be registered, c.f. 259 // common_types.h for the definition of 260 // CodecInst. 261 // 262 // Return value: 263 // -1 if failed to register, 264 // 0 if succeeded. 265 // 266 virtual int RegisterSecondarySendCodec(const CodecInst& send_codec) = 0; 267 268 /////////////////////////////////////////////////////////////////////////// 269 // void UnregisterSecondarySendCodec() 270 // Unregister the secondary encoder to disable dual-streaming. 271 // 272 virtual void UnregisterSecondarySendCodec() = 0; 273 274 /////////////////////////////////////////////////////////////////////////// 275 // int32_t SendCodec() 276 // Get parameters for the codec currently registered as send codec. 277 // 278 // Output: 279 // -current_send_codec : parameters of the send codec. 280 // 281 // Return value: 282 // -1 if failed to get send codec, 283 // 0 if succeeded. 284 // 285 virtual int32_t SendCodec(CodecInst* current_send_codec) const = 0; 286 287 /////////////////////////////////////////////////////////////////////////// 288 // int SecondarySendCodec() 289 // Get the codec parameters for the current secondary send codec. 290 // 291 // Output: 292 // -secondary_codec : parameters of the secondary send codec. 293 // 294 // Return value: 295 // -1 if failed to get send codec, 296 // 0 if succeeded. 297 // 298 virtual int SecondarySendCodec(CodecInst* secondary_codec) const = 0; 299 300 /////////////////////////////////////////////////////////////////////////// 301 // int32_t SendFrequency() 302 // Get the sampling frequency of the current encoder in Hertz. 303 // 304 // Return value: 305 // positive; sampling frequency [Hz] of the current encoder. 306 // -1 if an error has happened. 307 // 308 virtual int32_t SendFrequency() const = 0; 309 310 /////////////////////////////////////////////////////////////////////////// 311 // int32_t Bitrate() 312 // Get encoding bit-rate in bits per second. 313 // 314 // Return value: 315 // positive; encoding rate in bits/sec, 316 // -1 if an error is happened. 317 // 318 virtual int32_t SendBitrate() const = 0; 319 320 /////////////////////////////////////////////////////////////////////////// 321 // int32_t SetReceivedEstimatedBandwidth() 322 // Set available bandwidth [bits/sec] of the up-link channel. 323 // This information is used for traffic shaping, and is currently only 324 // supported if iSAC is the send codec. 325 // 326 // Input: 327 // -bw : bandwidth in bits/sec estimated for 328 // up-link. 329 // Return value 330 // -1 if error occurred in setting the bandwidth, 331 // 0 bandwidth is set successfully. 332 // 333 virtual int32_t SetReceivedEstimatedBandwidth( 334 const int32_t bw) = 0; 335 336 /////////////////////////////////////////////////////////////////////////// 337 // int32_t RegisterTransportCallback() 338 // Register a transport callback which will be called to deliver 339 // the encoded buffers whenever Process() is called and a 340 // bit-stream is ready. 341 // 342 // Input: 343 // -transport : pointer to the callback class 344 // transport->SendData() is called whenever 345 // Process() is called and bit-stream is ready 346 // to deliver. 347 // 348 // Return value: 349 // -1 if the transport callback could not be registered 350 // 0 if registration is successful. 351 // 352 virtual int32_t RegisterTransportCallback( 353 AudioPacketizationCallback* transport) = 0; 354 355 /////////////////////////////////////////////////////////////////////////// 356 // int32_t Add10MsData() 357 // Add 10MS of raw (PCM) audio data to the encoder. If the sampling 358 // frequency of the audio does not match the sampling frequency of the 359 // current encoder ACM will resample the audio. 360 // 361 // Input: 362 // -audio_frame : the input audio frame, containing raw audio 363 // sampling frequency etc., 364 // c.f. module_common_types.h for definition of 365 // AudioFrame. 366 // 367 // Return value: 368 // 0 successfully added the frame. 369 // -1 some error occurred and data is not added. 370 // < -1 to add the frame to the buffer n samples had to be 371 // overwritten, -n is the return value in this case. 372 // 373 virtual int32_t Add10MsData(const AudioFrame& audio_frame) = 0; 374 375 /////////////////////////////////////////////////////////////////////////// 376 // (RED) Redundant Coding 377 // 378 379 /////////////////////////////////////////////////////////////////////////// 380 // int32_t SetREDStatus() 381 // configure RED status i.e. on/off. 382 // 383 // RFC 2198 describes a solution which has a single payload type which 384 // signifies a packet with redundancy. That packet then becomes a container, 385 // encapsulating multiple payloads into a single RTP packet. 386 // Such a scheme is flexible, since any amount of redundancy may be 387 // encapsulated within a single packet. There is, however, a small overhead 388 // since each encapsulated payload must be preceded by a header indicating 389 // the type of data enclosed. 390 // 391 // Input: 392 // -enable_red : if true RED is enabled, otherwise RED is 393 // disabled. 394 // 395 // Return value: 396 // -1 if failed to set RED status, 397 // 0 if succeeded. 398 // 399 virtual int32_t SetREDStatus(bool enable_red) = 0; 400 401 /////////////////////////////////////////////////////////////////////////// 402 // bool REDStatus() 403 // Get RED status 404 // 405 // Return value: 406 // true if RED is enabled, 407 // false if RED is disabled. 408 // 409 virtual bool REDStatus() const = 0; 410 411 /////////////////////////////////////////////////////////////////////////// 412 // (FEC) Forward Error Correction (codec internal) 413 // 414 415 /////////////////////////////////////////////////////////////////////////// 416 // int32_t SetCodecFEC() 417 // Configures codec internal FEC status i.e. on/off. No effects on codecs that 418 // do not provide internal FEC. 419 // 420 // Input: 421 // -enable_fec : if true FEC will be enabled otherwise the FEC is 422 // disabled. 423 // 424 // Return value: 425 // -1 if failed, or the codec does not support FEC 426 // 0 if succeeded. 427 // 428 virtual int SetCodecFEC(bool enable_codec_fec) = 0; 429 430 /////////////////////////////////////////////////////////////////////////// 431 // bool CodecFEC() 432 // Gets status of codec internal FEC. 433 // 434 // Return value: 435 // true if FEC is enabled, 436 // false if FEC is disabled. 437 // 438 virtual bool CodecFEC() const = 0; 439 440 /////////////////////////////////////////////////////////////////////////// 441 // int SetPacketLossRate() 442 // Sets expected packet loss rate for encoding. Some encoders provide packet 443 // loss gnostic encoding to make stream less sensitive to packet losses, 444 // through e.g., FEC. No effects on codecs that do not provide such encoding. 445 // 446 // Input: 447 // -packet_loss_rate : expected packet loss rate (0 -- 100 inclusive). 448 // 449 // Return value 450 // -1 if failed to set packet loss rate, 451 // 0 if succeeded. 452 // 453 virtual int SetPacketLossRate(int packet_loss_rate) = 0; 454 455 /////////////////////////////////////////////////////////////////////////// 456 // (VAD) Voice Activity Detection 457 // 458 459 /////////////////////////////////////////////////////////////////////////// 460 // int32_t SetVAD() 461 // If DTX is enabled & the codec does not have internal DTX/VAD 462 // WebRtc VAD will be automatically enabled and |enable_vad| is ignored. 463 // 464 // If DTX is disabled but VAD is enabled no DTX packets are send, 465 // regardless of whether the codec has internal DTX/VAD or not. In this 466 // case, WebRtc VAD is running to label frames as active/in-active. 467 // 468 // NOTE! VAD/DTX is not supported when sending stereo. 469 // 470 // Inputs: 471 // -enable_dtx : if true DTX is enabled, 472 // otherwise DTX is disabled. 473 // -enable_vad : if true VAD is enabled, 474 // otherwise VAD is disabled. 475 // -vad_mode : determines the aggressiveness of VAD. A more 476 // aggressive mode results in more frames labeled 477 // as in-active, c.f. definition of 478 // ACMVADMode in audio_coding_module_typedefs.h 479 // for valid values. 480 // 481 // Return value: 482 // -1 if failed to set up VAD/DTX, 483 // 0 if succeeded. 484 // 485 virtual int32_t SetVAD(const bool enable_dtx = true, 486 const bool enable_vad = false, 487 const ACMVADMode vad_mode = VADNormal) = 0; 488 489 /////////////////////////////////////////////////////////////////////////// 490 // int32_t VAD() 491 // Get VAD status. 492 // 493 // Outputs: 494 // -dtx_enabled : is set to true if DTX is enabled, otherwise 495 // is set to false. 496 // -vad_enabled : is set to true if VAD is enabled, otherwise 497 // is set to false. 498 // -vad_mode : is set to the current aggressiveness of VAD. 499 // 500 // Return value: 501 // -1 if fails to retrieve the setting of DTX/VAD, 502 // 0 if succeeded. 503 // 504 virtual int32_t VAD(bool* dtx_enabled, bool* vad_enabled, 505 ACMVADMode* vad_mode) const = 0; 506 507 /////////////////////////////////////////////////////////////////////////// 508 // int32_t ReplaceInternalDTXWithWebRtc() 509 // Used to replace codec internal DTX scheme with WebRtc. This is only 510 // supported for G729, where this call replaces AnnexB with WebRtc DTX. 511 // 512 // Input: 513 // -use_webrtc_dtx : if false (default) the codec built-in DTX/VAD 514 // scheme is used, otherwise the internal DTX is 515 // replaced with WebRtc DTX/VAD. 516 // 517 // Return value: 518 // -1 if failed to replace codec internal DTX with WebRtc, 519 // 0 if succeeded. 520 // 521 virtual int32_t ReplaceInternalDTXWithWebRtc( 522 const bool use_webrtc_dtx = false) = 0; 523 524 /////////////////////////////////////////////////////////////////////////// 525 // int32_t IsInternalDTXReplacedWithWebRtc() 526 // Get status if the codec internal DTX (when such exists) is replaced with 527 // WebRtc DTX. This is only supported for G729. 528 // 529 // Output: 530 // -uses_webrtc_dtx : is set to true if the codec internal DTX is 531 // replaced with WebRtc DTX/VAD, otherwise it is set 532 // to false. 533 // 534 // Return value: 535 // -1 if failed to determine if codec internal DTX is replaced with WebRtc, 536 // 0 if succeeded. 537 // 538 virtual int32_t IsInternalDTXReplacedWithWebRtc( 539 bool* uses_webrtc_dtx) = 0; 540 541 /////////////////////////////////////////////////////////////////////////// 542 // int32_t RegisterVADCallback() 543 // Call this method to register a callback function which is called 544 // any time that ACM encounters an empty frame. That is a frame which is 545 // recognized inactive. Depending on the codec WebRtc VAD or internal codec 546 // VAD is employed to identify a frame as active/inactive. 547 // 548 // Input: 549 // -vad_callback : pointer to a callback function. 550 // 551 // Return value: 552 // -1 if failed to register the callback function. 553 // 0 if the callback function is registered successfully. 554 // 555 virtual int32_t RegisterVADCallback(ACMVADCallback* vad_callback) = 0; 556 557 /////////////////////////////////////////////////////////////////////////// 558 // Receiver 559 // 560 561 /////////////////////////////////////////////////////////////////////////// 562 // int32_t InitializeReceiver() 563 // Any decoder-related state of ACM will be initialized to the 564 // same state when ACM is created. This will not interrupt or 565 // effect encoding functionality of ACM. ACM would lose all the 566 // decoding-related settings by calling this function. 567 // For instance, all registered codecs are deleted and have to be 568 // registered again. 569 // 570 // Return value: 571 // -1 if failed to initialize, 572 // 0 if succeeded. 573 // 574 virtual int32_t InitializeReceiver() = 0; 575 576 /////////////////////////////////////////////////////////////////////////// 577 // int32_t ResetDecoder() 578 // This API resets the states of decoders. ACM will not lose any 579 // decoder-related settings, such as registered codecs. 580 // 581 // Return value: 582 // -1 if failed to initialize, 583 // 0 if succeeded. 584 // 585 virtual int32_t ResetDecoder() = 0; 586 587 /////////////////////////////////////////////////////////////////////////// 588 // int32_t ReceiveFrequency() 589 // Get sampling frequency of the last received payload. 590 // 591 // Return value: 592 // non-negative the sampling frequency in Hertz. 593 // -1 if an error has occurred. 594 // 595 virtual int32_t ReceiveFrequency() const = 0; 596 597 /////////////////////////////////////////////////////////////////////////// 598 // int32_t PlayoutFrequency() 599 // Get sampling frequency of audio played out. 600 // 601 // Return value: 602 // the sampling frequency in Hertz. 603 // 604 virtual int32_t PlayoutFrequency() const = 0; 605 606 /////////////////////////////////////////////////////////////////////////// 607 // int32_t RegisterReceiveCodec() 608 // Register possible decoders, can be called multiple times for 609 // codecs, CNG-NB, CNG-WB, CNG-SWB, AVT and RED. 610 // 611 // Input: 612 // -receive_codec : parameters of the codec to be registered, c.f. 613 // common_types.h for the definition of 614 // CodecInst. 615 // 616 // Return value: 617 // -1 if failed to register the codec 618 // 0 if the codec registered successfully. 619 // 620 virtual int32_t RegisterReceiveCodec( 621 const CodecInst& receive_codec) = 0; 622 623 /////////////////////////////////////////////////////////////////////////// 624 // int32_t UnregisterReceiveCodec() 625 // Unregister the codec currently registered with a specific payload type 626 // from the list of possible receive codecs. 627 // 628 // Input: 629 // -payload_type : The number representing the payload type to 630 // unregister. 631 // 632 // Output: 633 // -1 if fails to unregister. 634 // 0 if the given codec is successfully unregistered. 635 // 636 virtual int UnregisterReceiveCodec( 637 uint8_t payload_type) = 0; 638 639 /////////////////////////////////////////////////////////////////////////// 640 // int32_t ReceiveCodec() 641 // Get the codec associated with last received payload. 642 // 643 // Output: 644 // -curr_receive_codec : parameters of the codec associated with the last 645 // received payload, c.f. common_types.h for 646 // the definition of CodecInst. 647 // 648 // Return value: 649 // -1 if failed to retrieve the codec, 650 // 0 if the codec is successfully retrieved. 651 // 652 virtual int32_t ReceiveCodec(CodecInst* curr_receive_codec) const = 0; 653 654 /////////////////////////////////////////////////////////////////////////// 655 // int32_t IncomingPacket() 656 // Call this function to insert a parsed RTP packet into ACM. 657 // 658 // Inputs: 659 // -incoming_payload : received payload. 660 // -payload_len_bytes : the length of payload in bytes. 661 // -rtp_info : the relevant information retrieved from RTP 662 // header. 663 // 664 // Return value: 665 // -1 if failed to push in the payload 666 // 0 if payload is successfully pushed in. 667 // 668 virtual int32_t IncomingPacket(const uint8_t* incoming_payload, 669 const int32_t payload_len_bytes, 670 const WebRtcRTPHeader& rtp_info) = 0; 671 672 /////////////////////////////////////////////////////////////////////////// 673 // int32_t IncomingPayload() 674 // Call this API to push incoming payloads when there is no rtp-info. 675 // The rtp-info will be created in ACM. One usage for this API is when 676 // pre-encoded files are pushed in ACM 677 // 678 // Inputs: 679 // -incoming_payload : received payload. 680 // -payload_len_byte : the length, in bytes, of the received payload. 681 // -payload_type : the payload-type. This specifies which codec has 682 // to be used to decode the payload. 683 // -timestamp : send timestamp of the payload. ACM starts with 684 // a random value and increment it by the 685 // packet-size, which is given when the codec in 686 // question is registered by RegisterReceiveCodec(). 687 // Therefore, it is essential to have the timestamp 688 // if the frame-size differ from the registered 689 // value or if the incoming payload contains DTX 690 // packets. 691 // 692 // Return value: 693 // -1 if failed to push in the payload 694 // 0 if payload is successfully pushed in. 695 // 696 virtual int32_t IncomingPayload(const uint8_t* incoming_payload, 697 const int32_t payload_len_byte, 698 const uint8_t payload_type, 699 const uint32_t timestamp = 0) = 0; 700 701 /////////////////////////////////////////////////////////////////////////// 702 // int SetMinimumPlayoutDelay() 703 // Set a minimum for the playout delay, used for lip-sync. NetEq maintains 704 // such a delay unless channel condition yields to a higher delay. 705 // 706 // Input: 707 // -time_ms : minimum delay in milliseconds. 708 // 709 // Return value: 710 // -1 if failed to set the delay, 711 // 0 if the minimum delay is set. 712 // 713 virtual int SetMinimumPlayoutDelay(int time_ms) = 0; 714 715 /////////////////////////////////////////////////////////////////////////// 716 // int SetMaximumPlayoutDelay() 717 // Set a maximum for the playout delay 718 // 719 // Input: 720 // -time_ms : maximum delay in milliseconds. 721 // 722 // Return value: 723 // -1 if failed to set the delay, 724 // 0 if the maximum delay is set. 725 // 726 virtual int SetMaximumPlayoutDelay(int time_ms) = 0; 727 728 // 729 // The shortest latency, in milliseconds, required by jitter buffer. This 730 // is computed based on inter-arrival times and playout mode of NetEq. The 731 // actual delay is the maximum of least-required-delay and the minimum-delay 732 // specified by SetMinumumPlayoutDelay() API. 733 // 734 virtual int LeastRequiredDelayMs() const = 0; 735 736 /////////////////////////////////////////////////////////////////////////// 737 // int32_t SetDtmfPlayoutStatus() 738 // Configure DTMF playout, i.e. whether out-of-band 739 // DTMF tones are played or not. 740 // 741 // Input: 742 // -enable : if true to enable playout out-of-band DTMF tones, 743 // false to disable. 744 // 745 // Return value: 746 // -1 if the method fails, e.g. DTMF playout is not supported. 747 // 0 if the status is set successfully. 748 // 749 virtual int32_t SetDtmfPlayoutStatus(const bool enable) = 0; 750 751 /////////////////////////////////////////////////////////////////////////// 752 // bool DtmfPlayoutStatus() 753 // Get Dtmf playout status. 754 // 755 // Return value: 756 // true if out-of-band Dtmf tones are played, 757 // false if playout of Dtmf tones is disabled. 758 // 759 virtual bool DtmfPlayoutStatus() const = 0; 760 761 /////////////////////////////////////////////////////////////////////////// 762 // int32_t PlayoutTimestamp() 763 // The send timestamp of an RTP packet is associated with the decoded 764 // audio of the packet in question. This function returns the timestamp of 765 // the latest audio obtained by calling PlayoutData10ms(). 766 // 767 // Input: 768 // -timestamp : a reference to a uint32_t to receive the 769 // timestamp. 770 // Return value: 771 // 0 if the output is a correct timestamp. 772 // -1 if failed to output the correct timestamp. 773 // 774 // TODO(tlegrand): Change function to return the timestamp. 775 virtual int32_t PlayoutTimestamp(uint32_t* timestamp) = 0; 776 777 /////////////////////////////////////////////////////////////////////////// 778 // int32_t DecoderEstimatedBandwidth() 779 // Get the estimate of the Bandwidth, in bits/second, based on the incoming 780 // stream. This API is useful in one-way communication scenarios, where 781 // the bandwidth information is sent in an out-of-band fashion. 782 // Currently only supported if iSAC is registered as a receiver. 783 // 784 // Return value: 785 // >0 bandwidth in bits/second. 786 // -1 if failed to get a bandwidth estimate. 787 // 788 virtual int32_t DecoderEstimatedBandwidth() const = 0; 789 790 /////////////////////////////////////////////////////////////////////////// 791 // int32_t SetPlayoutMode() 792 // Call this API to set the playout mode. Playout mode could be optimized 793 // for i) voice, ii) FAX or iii) streaming. In Voice mode, NetEQ is 794 // optimized to deliver highest audio quality while maintaining a minimum 795 // delay. In FAX mode, NetEQ is optimized to have few delay changes as 796 // possible and maintain a constant delay, perhaps large relative to voice 797 // mode, to avoid PLC. In streaming mode, we tolerate a little more delay 798 // to achieve better jitter robustness. 799 // 800 // Input: 801 // -mode : playout mode. Possible inputs are: 802 // "voice", 803 // "fax" and 804 // "streaming". 805 // 806 // Return value: 807 // -1 if failed to set the mode, 808 // 0 if succeeding. 809 // 810 virtual int32_t SetPlayoutMode(const AudioPlayoutMode mode) = 0; 811 812 /////////////////////////////////////////////////////////////////////////// 813 // AudioPlayoutMode PlayoutMode() 814 // Get playout mode, i.e. whether it is speech, FAX or streaming. See 815 // audio_coding_module_typedefs.h for definition of AudioPlayoutMode. 816 // 817 // Return value: 818 // voice: is for voice output, 819 // fax: a mode that is optimized for receiving FAX signals. 820 // In this mode NetEq tries to maintain a constant high 821 // delay to avoid PLC if possible. 822 // streaming: a mode that is suitable for streaming. In this mode we 823 // accept longer delay to improve jitter robustness. 824 // 825 virtual AudioPlayoutMode PlayoutMode() const = 0; 826 827 /////////////////////////////////////////////////////////////////////////// 828 // int32_t PlayoutData10Ms( 829 // Get 10 milliseconds of raw audio data for playout, at the given sampling 830 // frequency. ACM will perform a resampling if required. 831 // 832 // Input: 833 // -desired_freq_hz : the desired sampling frequency, in Hertz, of the 834 // output audio. If set to -1, the function returns 835 // the audio at the current sampling frequency. 836 // 837 // Output: 838 // -audio_frame : output audio frame which contains raw audio data 839 // and other relevant parameters, c.f. 840 // module_common_types.h for the definition of 841 // AudioFrame. 842 // 843 // Return value: 844 // -1 if the function fails, 845 // 0 if the function succeeds. 846 // 847 virtual int32_t PlayoutData10Ms(int32_t desired_freq_hz, 848 AudioFrame* audio_frame) = 0; 849 850 /////////////////////////////////////////////////////////////////////////// 851 // Codec specific 852 // 853 854 /////////////////////////////////////////////////////////////////////////// 855 // int32_t SetISACMaxRate() 856 // Set the maximum instantaneous rate of iSAC. For a payload of B bits 857 // with a frame-size of T sec the instantaneous rate is B/T bits per 858 // second. Therefore, (B/T < |max_rate_bps|) and 859 // (B < |max_payload_len_bytes| * 8) are always satisfied for iSAC payloads, 860 // c.f SetISACMaxPayloadSize(). 861 // 862 // Input: 863 // -max_rate_bps : maximum instantaneous bit-rate given in bits/sec. 864 // 865 // Return value: 866 // -1 if failed to set the maximum rate. 867 // 0 if the maximum rate is set successfully. 868 // 869 virtual int SetISACMaxRate(int max_rate_bps) = 0; 870 871 /////////////////////////////////////////////////////////////////////////// 872 // int32_t SetISACMaxPayloadSize() 873 // Set the maximum payload size of iSAC packets. No iSAC payload, 874 // regardless of its frame-size, may exceed the given limit. For 875 // an iSAC payload of size B bits and frame-size T seconds we have; 876 // (B < |max_payload_len_bytes| * 8) and (B/T < |max_rate_bps|), c.f. 877 // SetISACMaxRate(). 878 // 879 // Input: 880 // -max_payload_len_bytes : maximum payload size in bytes. 881 // 882 // Return value: 883 // -1 if failed to set the maximum payload-size. 884 // 0 if the given length is set successfully. 885 // 886 virtual int SetISACMaxPayloadSize(int max_payload_len_bytes) = 0; 887 888 /////////////////////////////////////////////////////////////////////////// 889 // int32_t ConfigISACBandwidthEstimator() 890 // Call this function to configure the bandwidth estimator of ISAC. 891 // During the adaptation of bit-rate, iSAC automatically adjusts the 892 // frame-size (either 30 or 60 ms) to save on RTP header. The initial 893 // frame-size can be specified by the first argument. The configuration also 894 // regards the initial estimate of bandwidths. The estimator starts from 895 // this point and converges to the actual bottleneck. This is given by the 896 // second parameter. Furthermore, it is also possible to control the 897 // adaptation of frame-size. This is specified by the last parameter. 898 // 899 // Input: 900 // -init_frame_size_ms : initial frame-size in milliseconds. For iSAC-wb 901 // 30 ms and 60 ms (default) are acceptable values, 902 // and for iSAC-swb 30 ms is the only acceptable 903 // value. Zero indicates default value. 904 // -init_rate_bps : initial estimate of the bandwidth. Values 905 // between 10000 and 58000 are acceptable. 906 // -enforce_srame_size : if true, the frame-size will not be adapted. 907 // 908 // Return value: 909 // -1 if failed to configure the bandwidth estimator, 910 // 0 if the configuration was successfully applied. 911 // 912 virtual int32_t ConfigISACBandwidthEstimator( 913 int init_frame_size_ms, 914 int init_rate_bps, 915 bool enforce_frame_size = false) = 0; 916 917 /////////////////////////////////////////////////////////////////////////// 918 // statistics 919 // 920 921 /////////////////////////////////////////////////////////////////////////// 922 // int32_t NetworkStatistics() 923 // Get network statistics. Note that the internal statistics of NetEq are 924 // reset by this call. 925 // 926 // Input: 927 // -network_statistics : a structure that contains network statistics. 928 // 929 // Return value: 930 // -1 if failed to set the network statistics, 931 // 0 if statistics are set successfully. 932 // 933 virtual int32_t NetworkStatistics( 934 ACMNetworkStatistics* network_statistics) = 0; 935 936 // 937 // Set an initial delay for playout. 938 // An initial delay yields ACM playout silence until equivalent of |delay_ms| 939 // audio payload is accumulated in NetEq jitter. Thereafter, ACM pulls audio 940 // from NetEq in its regular fashion, and the given delay is maintained 941 // through out the call, unless channel conditions yield to a higher jitter 942 // buffer delay. 943 // 944 // Input: 945 // -delay_ms : delay in milliseconds. 946 // 947 // Return values: 948 // -1 if failed to set the delay. 949 // 0 if delay is set successfully. 950 // 951 virtual int SetInitialPlayoutDelay(int delay_ms) = 0; 952 953 // 954 // Enable NACK and set the maximum size of the NACK list. If NACK is already 955 // enable then the maximum NACK list size is modified accordingly. 956 // 957 // If the sequence number of last received packet is N, the sequence numbers 958 // of NACK list are in the range of [N - |max_nack_list_size|, N). 959 // 960 // |max_nack_list_size| should be positive (none zero) and less than or 961 // equal to |Nack::kNackListSizeLimit|. Otherwise, No change is applied and -1 962 // is returned. 0 is returned at success. 963 // 964 virtual int EnableNack(size_t max_nack_list_size) = 0; 965 966 // Disable NACK. 967 virtual void DisableNack() = 0; 968 969 // 970 // Get a list of packets to be retransmitted. |round_trip_time_ms| is an 971 // estimate of the round-trip-time (in milliseconds). Missing packets which 972 // will be playout in a shorter time than the round-trip-time (with respect 973 // to the time this API is called) will not be included in the list. 974 // 975 // Negative |round_trip_time_ms| results is an error message and empty list 976 // is returned. 977 // 978 virtual std::vector<uint16_t> GetNackList(int round_trip_time_ms) const = 0; 979 980 virtual void GetDecodingCallStatistics( 981 AudioDecodingCallStats* call_stats) const = 0; 982 }; 983 984 } // namespace webrtc 985 986 #endif // WEBRTC_MODULES_AUDIO_CODING_MAIN_INTERFACE_AUDIO_CODING_MODULE_H_ 987