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 <memory> 15 #include <string> 16 #include <utility> 17 #include <vector> 18 19 #include "absl/types/optional.h" 20 #include "api/audio_codecs/audio_decoder_factory.h" 21 #include "api/audio_codecs/audio_encoder.h" 22 #include "api/function_view.h" 23 #include "api/neteq/neteq.h" 24 #include "api/neteq/neteq_factory.h" 25 #include "modules/audio_coding/include/audio_coding_module_typedefs.h" 26 #include "system_wrappers/include/clock.h" 27 28 namespace webrtc { 29 30 // forward declarations 31 class AudioDecoder; 32 class AudioEncoder; 33 class AudioFrame; 34 struct RTPHeader; 35 36 // Callback class used for sending data ready to be packetized 37 class AudioPacketizationCallback { 38 public: ~AudioPacketizationCallback()39 virtual ~AudioPacketizationCallback() {} 40 SendData(AudioFrameType frame_type,uint8_t payload_type,uint32_t timestamp,const uint8_t * payload_data,size_t payload_len_bytes,int64_t absolute_capture_timestamp_ms)41 virtual int32_t SendData(AudioFrameType frame_type, 42 uint8_t payload_type, 43 uint32_t timestamp, 44 const uint8_t* payload_data, 45 size_t payload_len_bytes, 46 int64_t absolute_capture_timestamp_ms) { 47 // TODO(bugs.webrtc.org/10739): Deprecate the old SendData and make this one 48 // pure virtual. 49 return SendData(frame_type, payload_type, timestamp, payload_data, 50 payload_len_bytes); 51 } SendData(AudioFrameType frame_type,uint8_t payload_type,uint32_t timestamp,const uint8_t * payload_data,size_t payload_len_bytes)52 virtual int32_t SendData(AudioFrameType frame_type, 53 uint8_t payload_type, 54 uint32_t timestamp, 55 const uint8_t* payload_data, 56 size_t payload_len_bytes) { 57 RTC_NOTREACHED() << "This method must be overridden, or not used."; 58 return -1; 59 } 60 }; 61 62 class AudioCodingModule { 63 protected: AudioCodingModule()64 AudioCodingModule() {} 65 66 public: 67 struct Config { 68 explicit Config( 69 rtc::scoped_refptr<AudioDecoderFactory> decoder_factory = nullptr); 70 Config(const Config&); 71 ~Config(); 72 73 NetEq::Config neteq_config; 74 Clock* clock; 75 rtc::scoped_refptr<AudioDecoderFactory> decoder_factory; 76 NetEqFactory* neteq_factory = nullptr; 77 }; 78 79 static AudioCodingModule* Create(const Config& config); 80 virtual ~AudioCodingModule() = default; 81 82 /////////////////////////////////////////////////////////////////////////// 83 // Sender 84 // 85 86 // |modifier| is called exactly once with one argument: a pointer to the 87 // unique_ptr that holds the current encoder (which is null if there is no 88 // current encoder). For the duration of the call, |modifier| has exclusive 89 // access to the unique_ptr; it may call the encoder, steal the encoder and 90 // replace it with another encoder or with nullptr, etc. 91 virtual void ModifyEncoder( 92 rtc::FunctionView<void(std::unique_ptr<AudioEncoder>*)> modifier) = 0; 93 94 // Utility method for simply replacing the existing encoder with a new one. SetEncoder(std::unique_ptr<AudioEncoder> new_encoder)95 void SetEncoder(std::unique_ptr<AudioEncoder> new_encoder) { 96 ModifyEncoder([&](std::unique_ptr<AudioEncoder>* encoder) { 97 *encoder = std::move(new_encoder); 98 }); 99 } 100 101 // int32_t RegisterTransportCallback() 102 // Register a transport callback which will be called to deliver 103 // the encoded buffers whenever Process() is called and a 104 // bit-stream is ready. 105 // 106 // Input: 107 // -transport : pointer to the callback class 108 // transport->SendData() is called whenever 109 // Process() is called and bit-stream is ready 110 // to deliver. 111 // 112 // Return value: 113 // -1 if the transport callback could not be registered 114 // 0 if registration is successful. 115 // 116 virtual int32_t RegisterTransportCallback( 117 AudioPacketizationCallback* transport) = 0; 118 119 /////////////////////////////////////////////////////////////////////////// 120 // int32_t Add10MsData() 121 // Add 10MS of raw (PCM) audio data and encode it. If the sampling 122 // frequency of the audio does not match the sampling frequency of the 123 // current encoder ACM will resample the audio. If an encoded packet was 124 // produced, it will be delivered via the callback object registered using 125 // RegisterTransportCallback, and the return value from this function will 126 // be the number of bytes encoded. 127 // 128 // Input: 129 // -audio_frame : the input audio frame, containing raw audio 130 // sampling frequency etc. 131 // 132 // Return value: 133 // >= 0 number of bytes encoded. 134 // -1 some error occurred. 135 // 136 virtual int32_t Add10MsData(const AudioFrame& audio_frame) = 0; 137 138 /////////////////////////////////////////////////////////////////////////// 139 // int SetPacketLossRate() 140 // Sets expected packet loss rate for encoding. Some encoders provide packet 141 // loss gnostic encoding to make stream less sensitive to packet losses, 142 // through e.g., FEC. No effects on codecs that do not provide such encoding. 143 // 144 // Input: 145 // -packet_loss_rate : expected packet loss rate (0 -- 100 inclusive). 146 // 147 // Return value 148 // -1 if failed to set packet loss rate, 149 // 0 if succeeded. 150 // 151 // This is only used in test code that rely on old ACM APIs. 152 // TODO(minyue): Remove it when possible. 153 virtual int SetPacketLossRate(int packet_loss_rate) = 0; 154 155 /////////////////////////////////////////////////////////////////////////// 156 // Receiver 157 // 158 159 /////////////////////////////////////////////////////////////////////////// 160 // int32_t InitializeReceiver() 161 // Any decoder-related state of ACM will be initialized to the 162 // same state when ACM is created. This will not interrupt or 163 // effect encoding functionality of ACM. ACM would lose all the 164 // decoding-related settings by calling this function. 165 // For instance, all registered codecs are deleted and have to be 166 // registered again. 167 // 168 // Return value: 169 // -1 if failed to initialize, 170 // 0 if succeeded. 171 // 172 virtual int32_t InitializeReceiver() = 0; 173 174 // Replace any existing decoders with the given payload type -> decoder map. 175 virtual void SetReceiveCodecs( 176 const std::map<int, SdpAudioFormat>& codecs) = 0; 177 178 /////////////////////////////////////////////////////////////////////////// 179 // int32_t IncomingPacket() 180 // Call this function to insert a parsed RTP packet into ACM. 181 // 182 // Inputs: 183 // -incoming_payload : received payload. 184 // -payload_len_bytes : the length of payload in bytes. 185 // -rtp_info : the relevant information retrieved from RTP 186 // header. 187 // 188 // Return value: 189 // -1 if failed to push in the payload 190 // 0 if payload is successfully pushed in. 191 // 192 virtual int32_t IncomingPacket(const uint8_t* incoming_payload, 193 const size_t payload_len_bytes, 194 const RTPHeader& rtp_header) = 0; 195 196 /////////////////////////////////////////////////////////////////////////// 197 // int32_t PlayoutData10Ms( 198 // Get 10 milliseconds of raw audio data for playout, at the given sampling 199 // frequency. ACM will perform a resampling if required. 200 // 201 // Input: 202 // -desired_freq_hz : the desired sampling frequency, in Hertz, of the 203 // output audio. If set to -1, the function returns 204 // the audio at the current sampling frequency. 205 // 206 // Output: 207 // -audio_frame : output audio frame which contains raw audio data 208 // and other relevant parameters. 209 // -muted : if true, the sample data in audio_frame is not 210 // populated, and must be interpreted as all zero. 211 // 212 // Return value: 213 // -1 if the function fails, 214 // 0 if the function succeeds. 215 // 216 virtual int32_t PlayoutData10Ms(int32_t desired_freq_hz, 217 AudioFrame* audio_frame, 218 bool* muted) = 0; 219 220 /////////////////////////////////////////////////////////////////////////// 221 // statistics 222 // 223 224 /////////////////////////////////////////////////////////////////////////// 225 // int32_t GetNetworkStatistics() 226 // Get network statistics. Note that the internal statistics of NetEq are 227 // reset by this call. 228 // 229 // Input: 230 // -network_statistics : a structure that contains network statistics. 231 // 232 // Return value: 233 // -1 if failed to set the network statistics, 234 // 0 if statistics are set successfully. 235 // 236 virtual int32_t GetNetworkStatistics( 237 NetworkStatistics* network_statistics) = 0; 238 239 virtual ANAStats GetANAStats() const = 0; 240 }; 241 242 } // namespace webrtc 243 244 #endif // MODULES_AUDIO_CODING_INCLUDE_AUDIO_CODING_MODULE_H_ 245