audio_coding_module.h (5517B)
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 MODULES_AUDIO_CODING_INCLUDE_AUDIO_CODING_MODULE_H_ 12 #define MODULES_AUDIO_CODING_INCLUDE_AUDIO_CODING_MODULE_H_ 13 14 #include <cstddef> 15 #include <cstdint> 16 #include <memory> 17 #include <utility> 18 19 #include "api/audio_codecs/audio_encoder.h" 20 #include "api/function_view.h" 21 #include "modules/audio_coding/include/audio_coding_module_typedefs.h" 22 #include "rtc_base/checks.h" 23 24 namespace webrtc { 25 26 // forward declarations 27 class AudioDecoder; 28 class AudioEncoder; 29 class AudioFrame; 30 struct RTPHeader; 31 32 // Callback class used for sending data ready to be packetized 33 class AudioPacketizationCallback { 34 public: 35 virtual ~AudioPacketizationCallback() {} 36 37 virtual int32_t SendData(AudioFrameType frame_type, 38 uint8_t payload_type, 39 uint32_t timestamp, 40 const uint8_t* payload_data, 41 size_t payload_len_bytes, 42 int64_t /* absolute_capture_timestamp_ms */) { 43 // TODO(bugs.webrtc.org/10739): Deprecate the old SendData and make this one 44 // pure virtual. 45 return SendData(frame_type, payload_type, timestamp, payload_data, 46 payload_len_bytes); 47 } 48 virtual int32_t SendData(AudioFrameType /* frame_type */, 49 uint8_t /* payload_type */, 50 uint32_t /* timestamp */, 51 const uint8_t* /* payload_data */, 52 size_t /* payload_len_bytes */) { 53 RTC_DCHECK_NOTREACHED() << "This method must be overridden, or not used."; 54 return -1; 55 } 56 }; 57 58 class AudioCodingModule { 59 protected: 60 AudioCodingModule() {} 61 62 public: 63 static std::unique_ptr<AudioCodingModule> Create(); 64 virtual ~AudioCodingModule() = default; 65 66 // `modifier` is called exactly once with one argument: a pointer to the 67 // unique_ptr that holds the current encoder (which is null if there is no 68 // current encoder). For the duration of the call, `modifier` has exclusive 69 // access to the unique_ptr; it may call the encoder, steal the encoder and 70 // replace it with another encoder or with nullptr, etc. 71 virtual void ModifyEncoder( 72 FunctionView<void(std::unique_ptr<AudioEncoder>*)> modifier) = 0; 73 74 // Utility method for simply replacing the existing encoder with a new one. 75 void SetEncoder(std::unique_ptr<AudioEncoder> new_encoder) { 76 ModifyEncoder([&](std::unique_ptr<AudioEncoder>* encoder) { 77 *encoder = std::move(new_encoder); 78 }); 79 } 80 81 // Reset encoder and audio coding module. This throws away any audio passed 82 // and starts fresh. 83 virtual void Reset() = 0; 84 85 // int32_t RegisterTransportCallback() 86 // Register a transport callback which will be called to deliver 87 // the encoded buffers whenever Process() is called and a 88 // bit-stream is ready. 89 // 90 // Input: 91 // -transport : pointer to the callback class 92 // transport->SendData() is called whenever 93 // Process() is called and bit-stream is ready 94 // to deliver. 95 // 96 // Return value: 97 // -1 if the transport callback could not be registered 98 // 0 if registration is successful. 99 // 100 virtual int32_t RegisterTransportCallback( 101 AudioPacketizationCallback* transport) = 0; 102 103 /////////////////////////////////////////////////////////////////////////// 104 // int32_t Add10MsData() 105 // Add 10MS of raw (PCM) audio data and encode it. If the sampling 106 // frequency of the audio does not match the sampling frequency of the 107 // current encoder ACM will resample the audio. If an encoded packet was 108 // produced, it will be delivered via the callback object registered using 109 // RegisterTransportCallback, and the return value from this function will 110 // be the number of bytes encoded. 111 // 112 // Input: 113 // -audio_frame : the input audio frame, containing raw audio 114 // sampling frequency etc. 115 // 116 // Return value: 117 // >= 0 number of bytes encoded. 118 // -1 some error occurred. 119 // 120 virtual int32_t Add10MsData(const AudioFrame& audio_frame) = 0; 121 122 /////////////////////////////////////////////////////////////////////////// 123 // int SetPacketLossRate() 124 // Sets expected packet loss rate for encoding. Some encoders provide packet 125 // loss gnostic encoding to make stream less sensitive to packet losses, 126 // through e.g., FEC. No effects on codecs that do not provide such encoding. 127 // 128 // Input: 129 // -packet_loss_rate : expected packet loss rate (0 -- 100 inclusive). 130 // 131 // Return value 132 // -1 if failed to set packet loss rate, 133 // 0 if succeeded. 134 // 135 // This is only used in test code that rely on old ACM APIs. 136 // TODO(minyue): Remove it when possible. 137 virtual int SetPacketLossRate(int packet_loss_rate) = 0; 138 139 /////////////////////////////////////////////////////////////////////////// 140 // statistics 141 // 142 143 virtual ANAStats GetANAStats() const = 0; 144 145 virtual int GetTargetBitrate() const = 0; 146 }; 147 148 } // namespace webrtc 149 150 #endif // MODULES_AUDIO_CODING_INCLUDE_AUDIO_CODING_MODULE_H_