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_INCLUDE_AUDIO_CODING_MODULE_H_ 12 #define WEBRTC_MODULES_AUDIO_CODING_INCLUDE_AUDIO_CODING_MODULE_H_ 13 14 #include <memory> 15 #include <string> 16 #include <vector> 17 18 #include "webrtc/base/deprecation.h" 19 #include "webrtc/base/function_view.h" 20 #include "webrtc/base/optional.h" 21 #include "webrtc/common_types.h" 22 #include "webrtc/modules/audio_coding/codecs/audio_decoder_factory.h" 23 #include "webrtc/modules/audio_coding/include/audio_coding_module_typedefs.h" 24 #include "webrtc/modules/audio_coding/neteq/include/neteq.h" 25 #include "webrtc/modules/include/module.h" 26 #include "webrtc/system_wrappers/include/clock.h" 27 #include "webrtc/typedefs.h" 28 29 namespace webrtc { 30 31 // forward declarations 32 struct CodecInst; 33 struct WebRtcRTPHeader; 34 class AudioDecoder; 35 class AudioEncoder; 36 class AudioFrame; 37 class RTPFragmentationHeader; 38 39 #define WEBRTC_10MS_PCM_AUDIO 960 // 16 bits super wideband 48 kHz 40 41 // Callback class used for sending data ready to be packetized 42 class AudioPacketizationCallback { 43 public: ~AudioPacketizationCallback()44 virtual ~AudioPacketizationCallback() {} 45 46 virtual int32_t SendData(FrameType frame_type, 47 uint8_t payload_type, 48 uint32_t timestamp, 49 const uint8_t* payload_data, 50 size_t payload_len_bytes, 51 const RTPFragmentationHeader* fragmentation) = 0; 52 }; 53 54 // Callback class used for reporting VAD decision 55 class ACMVADCallback { 56 public: ~ACMVADCallback()57 virtual ~ACMVADCallback() {} 58 59 virtual int32_t InFrameType(FrameType frame_type) = 0; 60 }; 61 62 class AudioCodingModule { 63 protected: AudioCodingModule()64 AudioCodingModule() {} 65 66 public: 67 struct Config { 68 Config(); 69 Config(const Config&); 70 ~Config(); 71 72 int id; 73 NetEq::Config neteq_config; 74 Clock* clock; 75 rtc::scoped_refptr<AudioDecoderFactory> decoder_factory; 76 }; 77 78 /////////////////////////////////////////////////////////////////////////// 79 // Creation and destruction of a ACM. 80 // 81 // The second method is used for testing where a simulated clock can be 82 // injected into ACM. ACM will take the ownership of the object clock and 83 // delete it when destroyed. 84 // 85 static AudioCodingModule* Create(int id); 86 static AudioCodingModule* Create(int id, Clock* clock); 87 static AudioCodingModule* Create(const Config& config); 88 virtual ~AudioCodingModule() = default; 89 90 /////////////////////////////////////////////////////////////////////////// 91 // Utility functions 92 // 93 94 /////////////////////////////////////////////////////////////////////////// 95 // uint8_t NumberOfCodecs() 96 // Returns number of supported codecs. 97 // 98 // Return value: 99 // number of supported codecs. 100 /// 101 static int NumberOfCodecs(); 102 103 /////////////////////////////////////////////////////////////////////////// 104 // int32_t Codec() 105 // Get supported codec with list number. 106 // 107 // Input: 108 // -list_id : list number. 109 // 110 // Output: 111 // -codec : a structure where the parameters of the codec, 112 // given by list number is written to. 113 // 114 // Return value: 115 // -1 if the list number (list_id) is invalid. 116 // 0 if succeeded. 117 // 118 static int Codec(int list_id, CodecInst* codec); 119 120 /////////////////////////////////////////////////////////////////////////// 121 // int32_t Codec() 122 // Get supported codec with the given codec name, sampling frequency, and 123 // a given number of channels. 124 // 125 // Input: 126 // -payload_name : name of the codec. 127 // -sampling_freq_hz : sampling frequency of the codec. Note! for RED 128 // a sampling frequency of -1 is a valid input. 129 // -channels : number of channels ( 1 - mono, 2 - stereo). 130 // 131 // Output: 132 // -codec : a structure where the function returns the 133 // default parameters of the codec. 134 // 135 // Return value: 136 // -1 if no codec matches the given parameters. 137 // 0 if succeeded. 138 // 139 static int Codec(const char* payload_name, CodecInst* codec, 140 int sampling_freq_hz, size_t channels); 141 142 /////////////////////////////////////////////////////////////////////////// 143 // int32_t Codec() 144 // 145 // Returns the list number of the given codec name, sampling frequency, and 146 // a given number of channels. 147 // 148 // Input: 149 // -payload_name : name of the codec. 150 // -sampling_freq_hz : sampling frequency of the codec. Note! for RED 151 // a sampling frequency of -1 is a valid input. 152 // -channels : number of channels ( 1 - mono, 2 - stereo). 153 // 154 // Return value: 155 // if the codec is found, the index of the codec in the list, 156 // -1 if the codec is not found. 157 // 158 static int Codec(const char* payload_name, int sampling_freq_hz, 159 size_t channels); 160 161 /////////////////////////////////////////////////////////////////////////// 162 // bool IsCodecValid() 163 // Checks the validity of the parameters of the given codec. 164 // 165 // Input: 166 // -codec : the structure which keeps the parameters of the 167 // codec. 168 // 169 // Return value: 170 // true if the parameters are valid, 171 // false if any parameter is not valid. 172 // 173 static bool IsCodecValid(const CodecInst& codec); 174 175 /////////////////////////////////////////////////////////////////////////// 176 // Sender 177 // 178 179 /////////////////////////////////////////////////////////////////////////// 180 // int32_t RegisterSendCodec() 181 // Registers a codec, specified by |send_codec|, as sending codec. 182 // This API can be called multiple of times to register Codec. The last codec 183 // registered overwrites the previous ones. 184 // The API can also be used to change payload type for CNG and RED, which are 185 // registered by default to default payload types. 186 // Note that registering CNG and RED won't overwrite speech codecs. 187 // This API can be called to set/change the send payload-type, frame-size 188 // or encoding rate (if applicable for the codec). 189 // 190 // Note: If a stereo codec is registered as send codec, VAD/DTX will 191 // automatically be turned off, since it is not supported for stereo sending. 192 // 193 // Note: If a secondary encoder is already registered, and the new send-codec 194 // has a sampling rate that does not match the secondary encoder, the 195 // secondary encoder will be unregistered. 196 // 197 // Input: 198 // -send_codec : Parameters of the codec to be registered, c.f. 199 // common_types.h for the definition of 200 // CodecInst. 201 // 202 // Return value: 203 // -1 if failed to initialize, 204 // 0 if succeeded. 205 // 206 virtual int32_t RegisterSendCodec(const CodecInst& send_codec) = 0; 207 208 // Registers |external_speech_encoder| as encoder. The new encoder will 209 // replace any previously registered speech encoder (internal or external). 210 virtual void RegisterExternalSendCodec( 211 AudioEncoder* external_speech_encoder) = 0; 212 213 // |modifier| is called exactly once with one argument: a pointer to the 214 // unique_ptr that holds the current encoder (which is null if there is no 215 // current encoder). For the duration of the call, |modifier| has exclusive 216 // access to the unique_ptr; it may call the encoder, steal the encoder and 217 // replace it with another encoder or with nullptr, etc. 218 virtual void ModifyEncoder( 219 rtc::FunctionView<void(std::unique_ptr<AudioEncoder>*)> modifier) = 0; 220 221 // |modifier| is called exactly once with one argument: a const pointer to the 222 // current encoder (which is null if there is no current encoder). 223 virtual void QueryEncoder( 224 rtc::FunctionView<void(AudioEncoder const*)> query) = 0; 225 226 // Utility method for simply replacing the existing encoder with a new one. SetEncoder(std::unique_ptr<AudioEncoder> new_encoder)227 void SetEncoder(std::unique_ptr<AudioEncoder> new_encoder) { 228 ModifyEncoder([&](std::unique_ptr<AudioEncoder>* encoder) { 229 *encoder = std::move(new_encoder); 230 }); 231 } 232 233 /////////////////////////////////////////////////////////////////////////// 234 // int32_t SendCodec() 235 // Get parameters for the codec currently registered as send codec. 236 // 237 // Return value: 238 // The send codec, or nothing if we don't have one 239 // 240 virtual rtc::Optional<CodecInst> SendCodec() const = 0; 241 242 /////////////////////////////////////////////////////////////////////////// 243 // int32_t SendFrequency() 244 // Get the sampling frequency of the current encoder in Hertz. 245 // 246 // Return value: 247 // positive; sampling frequency [Hz] of the current encoder. 248 // -1 if an error has happened. 249 // 250 virtual int32_t SendFrequency() const = 0; 251 252 /////////////////////////////////////////////////////////////////////////// 253 // Sets the bitrate to the specified value in bits/sec. If the value is not 254 // supported by the codec, it will choose another appropriate value. 255 // 256 // This is only used in test code that rely on old ACM APIs. 257 // TODO(minyue): Remove it when possible. 258 virtual void SetBitRate(int bitrate_bps) = 0; 259 260 // int32_t RegisterTransportCallback() 261 // Register a transport callback which will be called to deliver 262 // the encoded buffers whenever Process() is called and a 263 // bit-stream is ready. 264 // 265 // Input: 266 // -transport : pointer to the callback class 267 // transport->SendData() is called whenever 268 // Process() is called and bit-stream is ready 269 // to deliver. 270 // 271 // Return value: 272 // -1 if the transport callback could not be registered 273 // 0 if registration is successful. 274 // 275 virtual int32_t RegisterTransportCallback( 276 AudioPacketizationCallback* transport) = 0; 277 278 /////////////////////////////////////////////////////////////////////////// 279 // int32_t Add10MsData() 280 // Add 10MS of raw (PCM) audio data and encode it. If the sampling 281 // frequency of the audio does not match the sampling frequency of the 282 // current encoder ACM will resample the audio. If an encoded packet was 283 // produced, it will be delivered via the callback object registered using 284 // RegisterTransportCallback, and the return value from this function will 285 // be the number of bytes encoded. 286 // 287 // Input: 288 // -audio_frame : the input audio frame, containing raw audio 289 // sampling frequency etc., 290 // c.f. module_common_types.h for definition of 291 // AudioFrame. 292 // 293 // Return value: 294 // >= 0 number of bytes encoded. 295 // -1 some error occurred. 296 // 297 virtual int32_t Add10MsData(const AudioFrame& audio_frame) = 0; 298 299 /////////////////////////////////////////////////////////////////////////// 300 // (RED) Redundant Coding 301 // 302 303 /////////////////////////////////////////////////////////////////////////// 304 // int32_t SetREDStatus() 305 // configure RED status i.e. on/off. 306 // 307 // RFC 2198 describes a solution which has a single payload type which 308 // signifies a packet with redundancy. That packet then becomes a container, 309 // encapsulating multiple payloads into a single RTP packet. 310 // Such a scheme is flexible, since any amount of redundancy may be 311 // encapsulated within a single packet. There is, however, a small overhead 312 // since each encapsulated payload must be preceded by a header indicating 313 // the type of data enclosed. 314 // 315 // Input: 316 // -enable_red : if true RED is enabled, otherwise RED is 317 // disabled. 318 // 319 // Return value: 320 // -1 if failed to set RED status, 321 // 0 if succeeded. 322 // 323 virtual int32_t SetREDStatus(bool enable_red) = 0; 324 325 /////////////////////////////////////////////////////////////////////////// 326 // bool REDStatus() 327 // Get RED status 328 // 329 // Return value: 330 // true if RED is enabled, 331 // false if RED is disabled. 332 // 333 virtual bool REDStatus() const = 0; 334 335 /////////////////////////////////////////////////////////////////////////// 336 // (FEC) Forward Error Correction (codec internal) 337 // 338 339 /////////////////////////////////////////////////////////////////////////// 340 // int32_t SetCodecFEC() 341 // Configures codec internal FEC status i.e. on/off. No effects on codecs that 342 // do not provide internal FEC. 343 // 344 // Input: 345 // -enable_fec : if true FEC will be enabled otherwise the FEC is 346 // disabled. 347 // 348 // Return value: 349 // -1 if failed, or the codec does not support FEC 350 // 0 if succeeded. 351 // 352 virtual int SetCodecFEC(bool enable_codec_fec) = 0; 353 354 /////////////////////////////////////////////////////////////////////////// 355 // bool CodecFEC() 356 // Gets status of codec internal FEC. 357 // 358 // Return value: 359 // true if FEC is enabled, 360 // false if FEC is disabled. 361 // 362 virtual bool CodecFEC() const = 0; 363 364 /////////////////////////////////////////////////////////////////////////// 365 // int SetPacketLossRate() 366 // Sets expected packet loss rate for encoding. Some encoders provide packet 367 // loss gnostic encoding to make stream less sensitive to packet losses, 368 // through e.g., FEC. No effects on codecs that do not provide such encoding. 369 // 370 // Input: 371 // -packet_loss_rate : expected packet loss rate (0 -- 100 inclusive). 372 // 373 // Return value 374 // -1 if failed to set packet loss rate, 375 // 0 if succeeded. 376 // 377 // This is only used in test code that rely on old ACM APIs. 378 // TODO(minyue): Remove it when possible. 379 virtual int SetPacketLossRate(int packet_loss_rate) = 0; 380 381 /////////////////////////////////////////////////////////////////////////// 382 // (VAD) Voice Activity Detection 383 // 384 385 /////////////////////////////////////////////////////////////////////////// 386 // int32_t SetVAD() 387 // If DTX is enabled & the codec does not have internal DTX/VAD 388 // WebRtc VAD will be automatically enabled and |enable_vad| is ignored. 389 // 390 // If DTX is disabled but VAD is enabled no DTX packets are send, 391 // regardless of whether the codec has internal DTX/VAD or not. In this 392 // case, WebRtc VAD is running to label frames as active/in-active. 393 // 394 // NOTE! VAD/DTX is not supported when sending stereo. 395 // 396 // Inputs: 397 // -enable_dtx : if true DTX is enabled, 398 // otherwise DTX is disabled. 399 // -enable_vad : if true VAD is enabled, 400 // otherwise VAD is disabled. 401 // -vad_mode : determines the aggressiveness of VAD. A more 402 // aggressive mode results in more frames labeled 403 // as in-active, c.f. definition of 404 // ACMVADMode in audio_coding_module_typedefs.h 405 // for valid values. 406 // 407 // Return value: 408 // -1 if failed to set up VAD/DTX, 409 // 0 if succeeded. 410 // 411 virtual int32_t SetVAD(const bool enable_dtx = true, 412 const bool enable_vad = false, 413 const ACMVADMode vad_mode = VADNormal) = 0; 414 415 /////////////////////////////////////////////////////////////////////////// 416 // int32_t VAD() 417 // Get VAD status. 418 // 419 // Outputs: 420 // -dtx_enabled : is set to true if DTX is enabled, otherwise 421 // is set to false. 422 // -vad_enabled : is set to true if VAD is enabled, otherwise 423 // is set to false. 424 // -vad_mode : is set to the current aggressiveness of VAD. 425 // 426 // Return value: 427 // -1 if fails to retrieve the setting of DTX/VAD, 428 // 0 if succeeded. 429 // 430 virtual int32_t VAD(bool* dtx_enabled, bool* vad_enabled, 431 ACMVADMode* vad_mode) const = 0; 432 433 /////////////////////////////////////////////////////////////////////////// 434 // int32_t RegisterVADCallback() 435 // Call this method to register a callback function which is called 436 // any time that ACM encounters an empty frame. That is a frame which is 437 // recognized inactive. Depending on the codec WebRtc VAD or internal codec 438 // VAD is employed to identify a frame as active/inactive. 439 // 440 // Input: 441 // -vad_callback : pointer to a callback function. 442 // 443 // Return value: 444 // -1 if failed to register the callback function. 445 // 0 if the callback function is registered successfully. 446 // 447 virtual int32_t RegisterVADCallback(ACMVADCallback* vad_callback) = 0; 448 449 /////////////////////////////////////////////////////////////////////////// 450 // Receiver 451 // 452 453 /////////////////////////////////////////////////////////////////////////// 454 // int32_t InitializeReceiver() 455 // Any decoder-related state of ACM will be initialized to the 456 // same state when ACM is created. This will not interrupt or 457 // effect encoding functionality of ACM. ACM would lose all the 458 // decoding-related settings by calling this function. 459 // For instance, all registered codecs are deleted and have to be 460 // registered again. 461 // 462 // Return value: 463 // -1 if failed to initialize, 464 // 0 if succeeded. 465 // 466 virtual int32_t InitializeReceiver() = 0; 467 468 /////////////////////////////////////////////////////////////////////////// 469 // int32_t ReceiveFrequency() 470 // Get sampling frequency of the last received payload. 471 // 472 // Return value: 473 // non-negative the sampling frequency in Hertz. 474 // -1 if an error has occurred. 475 // 476 virtual int32_t ReceiveFrequency() const = 0; 477 478 /////////////////////////////////////////////////////////////////////////// 479 // int32_t PlayoutFrequency() 480 // Get sampling frequency of audio played out. 481 // 482 // Return value: 483 // the sampling frequency in Hertz. 484 // 485 virtual int32_t PlayoutFrequency() const = 0; 486 487 // Registers a decoder for the given payload type. Returns true iff 488 // successful. 489 virtual bool RegisterReceiveCodec(int rtp_payload_type, 490 const SdpAudioFormat& audio_format) = 0; 491 492 /////////////////////////////////////////////////////////////////////////// 493 // int32_t RegisterReceiveCodec() 494 // Register possible decoders, can be called multiple times for 495 // codecs, CNG-NB, CNG-WB, CNG-SWB, AVT and RED. 496 // 497 // Input: 498 // -receive_codec : parameters of the codec to be registered, c.f. 499 // common_types.h for the definition of 500 // CodecInst. 501 // 502 // Return value: 503 // -1 if failed to register the codec 504 // 0 if the codec registered successfully. 505 // 506 virtual int RegisterReceiveCodec(const CodecInst& receive_codec) = 0; 507 508 // Register a decoder; call repeatedly to register multiple decoders. |df| is 509 // a decoder factory that returns an iSAC decoder; it will be called once if 510 // the decoder being registered is iSAC. 511 virtual int RegisterReceiveCodec( 512 const CodecInst& receive_codec, 513 rtc::FunctionView<std::unique_ptr<AudioDecoder>()> isac_factory) = 0; 514 515 // Registers an external decoder. The name is only used to provide information 516 // back to the caller about the decoder. Hence, the name is arbitrary, and may 517 // be empty. 518 virtual int RegisterExternalReceiveCodec(int rtp_payload_type, 519 AudioDecoder* external_decoder, 520 int sample_rate_hz, 521 int num_channels, 522 const std::string& name) = 0; 523 524 /////////////////////////////////////////////////////////////////////////// 525 // int32_t UnregisterReceiveCodec() 526 // Unregister the codec currently registered with a specific payload type 527 // from the list of possible receive codecs. 528 // 529 // Input: 530 // -payload_type : The number representing the payload type to 531 // unregister. 532 // 533 // Output: 534 // -1 if fails to unregister. 535 // 0 if the given codec is successfully unregistered. 536 // 537 virtual int UnregisterReceiveCodec( 538 uint8_t payload_type) = 0; 539 540 /////////////////////////////////////////////////////////////////////////// 541 // int32_t ReceiveCodec() 542 // Get the codec associated with last received payload. 543 // 544 // Output: 545 // -curr_receive_codec : parameters of the codec associated with the last 546 // received payload, c.f. common_types.h for 547 // the definition of CodecInst. 548 // 549 // Return value: 550 // -1 if failed to retrieve the codec, 551 // 0 if the codec is successfully retrieved. 552 // 553 virtual int32_t ReceiveCodec(CodecInst* curr_receive_codec) const = 0; 554 555 /////////////////////////////////////////////////////////////////////////// 556 // rtc::Optional<SdpAudioFormat> ReceiveFormat() 557 // Get the format associated with last received payload. 558 // 559 // Return value: 560 // An SdpAudioFormat describing the format associated with the last 561 // received payload. 562 // An empty Optional if no payload has yet been received. 563 // 564 virtual rtc::Optional<SdpAudioFormat> ReceiveFormat() const = 0; 565 566 /////////////////////////////////////////////////////////////////////////// 567 // int32_t IncomingPacket() 568 // Call this function to insert a parsed RTP packet into ACM. 569 // 570 // Inputs: 571 // -incoming_payload : received payload. 572 // -payload_len_bytes : the length of payload in bytes. 573 // -rtp_info : the relevant information retrieved from RTP 574 // header. 575 // 576 // Return value: 577 // -1 if failed to push in the payload 578 // 0 if payload is successfully pushed in. 579 // 580 virtual int32_t IncomingPacket(const uint8_t* incoming_payload, 581 const size_t payload_len_bytes, 582 const WebRtcRTPHeader& rtp_info) = 0; 583 584 /////////////////////////////////////////////////////////////////////////// 585 // int32_t IncomingPayload() 586 // Call this API to push incoming payloads when there is no rtp-info. 587 // The rtp-info will be created in ACM. One usage for this API is when 588 // pre-encoded files are pushed in ACM 589 // 590 // Inputs: 591 // -incoming_payload : received payload. 592 // -payload_len_byte : the length, in bytes, of the received payload. 593 // -payload_type : the payload-type. This specifies which codec has 594 // to be used to decode the payload. 595 // -timestamp : send timestamp of the payload. ACM starts with 596 // a random value and increment it by the 597 // packet-size, which is given when the codec in 598 // question is registered by RegisterReceiveCodec(). 599 // Therefore, it is essential to have the timestamp 600 // if the frame-size differ from the registered 601 // value or if the incoming payload contains DTX 602 // packets. 603 // 604 // Return value: 605 // -1 if failed to push in the payload 606 // 0 if payload is successfully pushed in. 607 // 608 virtual int32_t IncomingPayload(const uint8_t* incoming_payload, 609 const size_t payload_len_byte, 610 const uint8_t payload_type, 611 const uint32_t timestamp = 0) = 0; 612 613 /////////////////////////////////////////////////////////////////////////// 614 // int SetMinimumPlayoutDelay() 615 // Set a minimum for the playout delay, used for lip-sync. NetEq maintains 616 // such a delay unless channel condition yields to a higher delay. 617 // 618 // Input: 619 // -time_ms : minimum delay in milliseconds. 620 // 621 // Return value: 622 // -1 if failed to set the delay, 623 // 0 if the minimum delay is set. 624 // 625 virtual int SetMinimumPlayoutDelay(int time_ms) = 0; 626 627 /////////////////////////////////////////////////////////////////////////// 628 // int SetMaximumPlayoutDelay() 629 // Set a maximum for the playout delay 630 // 631 // Input: 632 // -time_ms : maximum delay in milliseconds. 633 // 634 // Return value: 635 // -1 if failed to set the delay, 636 // 0 if the maximum delay is set. 637 // 638 virtual int SetMaximumPlayoutDelay(int time_ms) = 0; 639 640 // 641 // The shortest latency, in milliseconds, required by jitter buffer. This 642 // is computed based on inter-arrival times and playout mode of NetEq. The 643 // actual delay is the maximum of least-required-delay and the minimum-delay 644 // specified by SetMinumumPlayoutDelay() API. 645 // 646 virtual int LeastRequiredDelayMs() const = 0; 647 648 // int32_t PlayoutTimestamp() 649 // The send timestamp of an RTP packet is associated with the decoded 650 // audio of the packet in question. This function returns the timestamp of 651 // the latest audio obtained by calling PlayoutData10ms(). 652 // 653 // Input: 654 // -timestamp : a reference to a uint32_t to receive the 655 // timestamp. 656 // Return value: 657 // 0 if the output is a correct timestamp. 658 // -1 if failed to output the correct timestamp. 659 // 660 RTC_DEPRECATED virtual int32_t PlayoutTimestamp(uint32_t* timestamp) = 0; 661 662 /////////////////////////////////////////////////////////////////////////// 663 // int32_t PlayoutTimestamp() 664 // The send timestamp of an RTP packet is associated with the decoded 665 // audio of the packet in question. This function returns the timestamp of 666 // the latest audio obtained by calling PlayoutData10ms(), or empty if no 667 // valid timestamp is available. 668 // 669 virtual rtc::Optional<uint32_t> PlayoutTimestamp() = 0; 670 671 /////////////////////////////////////////////////////////////////////////// 672 // int FilteredCurrentDelayMs() 673 // Returns the current total delay from NetEq (packet buffer and sync buffer) 674 // in ms, with smoothing applied to even out short-time fluctuations due to 675 // jitter. The packet buffer part of the delay is not updated during DTX/CNG 676 // periods. 677 // 678 virtual int FilteredCurrentDelayMs() const = 0; 679 680 /////////////////////////////////////////////////////////////////////////// 681 // int32_t PlayoutData10Ms( 682 // Get 10 milliseconds of raw audio data for playout, at the given sampling 683 // frequency. ACM will perform a resampling if required. 684 // 685 // Input: 686 // -desired_freq_hz : the desired sampling frequency, in Hertz, of the 687 // output audio. If set to -1, the function returns 688 // the audio at the current sampling frequency. 689 // 690 // Output: 691 // -audio_frame : output audio frame which contains raw audio data 692 // and other relevant parameters, c.f. 693 // module_common_types.h for the definition of 694 // AudioFrame. 695 // -muted : if true, the sample data in audio_frame is not 696 // populated, and must be interpreted as all zero. 697 // 698 // Return value: 699 // -1 if the function fails, 700 // 0 if the function succeeds. 701 // 702 virtual int32_t PlayoutData10Ms(int32_t desired_freq_hz, 703 AudioFrame* audio_frame, 704 bool* muted) = 0; 705 706 ///////////////////////////////////////////////////////////////////////////// 707 // Same as above, but without the muted parameter. This methods should not be 708 // used if enable_fast_accelerate was set to true in NetEq::Config. 709 // TODO(henrik.lundin) Remove this method when downstream dependencies are 710 // ready. 711 virtual int32_t PlayoutData10Ms(int32_t desired_freq_hz, 712 AudioFrame* audio_frame) = 0; 713 714 /////////////////////////////////////////////////////////////////////////// 715 // Codec specific 716 // 717 718 /////////////////////////////////////////////////////////////////////////// 719 // int SetOpusApplication() 720 // Sets the intended application if current send codec is Opus. Opus uses this 721 // to optimize the encoding for applications like VOIP and music. Currently, 722 // two modes are supported: kVoip and kAudio. 723 // 724 // Input: 725 // - application : intended application. 726 // 727 // Return value: 728 // -1 if current send codec is not Opus or error occurred in setting the 729 // Opus application mode. 730 // 0 if the Opus application mode is successfully set. 731 // 732 virtual int SetOpusApplication(OpusApplicationMode application) = 0; 733 734 /////////////////////////////////////////////////////////////////////////// 735 // int SetOpusMaxPlaybackRate() 736 // If current send codec is Opus, informs it about maximum playback rate the 737 // receiver will render. Opus can use this information to optimize the bit 738 // rate and increase the computation efficiency. 739 // 740 // Input: 741 // -frequency_hz : maximum playback rate in Hz. 742 // 743 // Return value: 744 // -1 if current send codec is not Opus or 745 // error occurred in setting the maximum playback rate, 746 // 0 if maximum bandwidth is set successfully. 747 // 748 virtual int SetOpusMaxPlaybackRate(int frequency_hz) = 0; 749 750 /////////////////////////////////////////////////////////////////////////// 751 // EnableOpusDtx() 752 // Enable the DTX, if current send codec is Opus. 753 // 754 // Return value: 755 // -1 if current send codec is not Opus or error occurred in enabling the 756 // Opus DTX. 757 // 0 if Opus DTX is enabled successfully. 758 // 759 virtual int EnableOpusDtx() = 0; 760 761 /////////////////////////////////////////////////////////////////////////// 762 // int DisableOpusDtx() 763 // If current send codec is Opus, disables its internal DTX. 764 // 765 // Return value: 766 // -1 if current send codec is not Opus or error occurred in disabling DTX. 767 // 0 if Opus DTX is disabled successfully. 768 // 769 virtual int DisableOpusDtx() = 0; 770 771 /////////////////////////////////////////////////////////////////////////// 772 // statistics 773 // 774 775 /////////////////////////////////////////////////////////////////////////// 776 // int32_t GetNetworkStatistics() 777 // Get network statistics. Note that the internal statistics of NetEq are 778 // reset by this call. 779 // 780 // Input: 781 // -network_statistics : a structure that contains network statistics. 782 // 783 // Return value: 784 // -1 if failed to set the network statistics, 785 // 0 if statistics are set successfully. 786 // 787 virtual int32_t GetNetworkStatistics( 788 NetworkStatistics* network_statistics) = 0; 789 790 // 791 // Enable NACK and set the maximum size of the NACK list. If NACK is already 792 // enable then the maximum NACK list size is modified accordingly. 793 // 794 // If the sequence number of last received packet is N, the sequence numbers 795 // of NACK list are in the range of [N - |max_nack_list_size|, N). 796 // 797 // |max_nack_list_size| should be positive (none zero) and less than or 798 // equal to |Nack::kNackListSizeLimit|. Otherwise, No change is applied and -1 799 // is returned. 0 is returned at success. 800 // 801 virtual int EnableNack(size_t max_nack_list_size) = 0; 802 803 // Disable NACK. 804 virtual void DisableNack() = 0; 805 806 // 807 // Get a list of packets to be retransmitted. |round_trip_time_ms| is an 808 // estimate of the round-trip-time (in milliseconds). Missing packets which 809 // will be playout in a shorter time than the round-trip-time (with respect 810 // to the time this API is called) will not be included in the list. 811 // 812 // Negative |round_trip_time_ms| results is an error message and empty list 813 // is returned. 814 // 815 virtual std::vector<uint16_t> GetNackList( 816 int64_t round_trip_time_ms) const = 0; 817 818 virtual void GetDecodingCallStatistics( 819 AudioDecodingCallStats* call_stats) const = 0; 820 }; 821 822 } // namespace webrtc 823 824 #endif // WEBRTC_MODULES_AUDIO_CODING_INCLUDE_AUDIO_CODING_MODULE_H_ 825