1 /* 2 * Copyright (c) 2013 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_ACM2_ACM_RECEIVER_H_ 12 #define WEBRTC_MODULES_AUDIO_CODING_ACM2_ACM_RECEIVER_H_ 13 14 #include <map> 15 #include <string> 16 #include <vector> 17 18 #include "webrtc/base/array_view.h" 19 #include "webrtc/base/optional.h" 20 #include "webrtc/base/scoped_ptr.h" 21 #include "webrtc/base/thread_annotations.h" 22 #include "webrtc/common_audio/vad/include/webrtc_vad.h" 23 #include "webrtc/engine_configurations.h" 24 #include "webrtc/modules/audio_coding/include/audio_coding_module.h" 25 #include "webrtc/modules/audio_coding/acm2/acm_resampler.h" 26 #include "webrtc/modules/audio_coding/acm2/call_statistics.h" 27 #include "webrtc/modules/audio_coding/acm2/initial_delay_manager.h" 28 #include "webrtc/modules/audio_coding/neteq/include/neteq.h" 29 #include "webrtc/modules/include/module_common_types.h" 30 #include "webrtc/typedefs.h" 31 32 namespace webrtc { 33 34 struct CodecInst; 35 class CriticalSectionWrapper; 36 class NetEq; 37 38 namespace acm2 { 39 40 class AcmReceiver { 41 public: 42 struct Decoder { 43 int acm_codec_id; 44 uint8_t payload_type; 45 // This field is meaningful for codecs where both mono and 46 // stereo versions are registered under the same ID. 47 size_t channels; 48 int sample_rate_hz; 49 }; 50 51 // Constructor of the class 52 explicit AcmReceiver(const AudioCodingModule::Config& config); 53 54 // Destructor of the class. 55 ~AcmReceiver(); 56 57 // 58 // Inserts a payload with its associated RTP-header into NetEq. 59 // 60 // Input: 61 // - rtp_header : RTP header for the incoming payload containing 62 // information about payload type, sequence number, 63 // timestamp, SSRC and marker bit. 64 // - incoming_payload : Incoming audio payload. 65 // - length_payload : Length of incoming audio payload in bytes. 66 // 67 // Return value : 0 if OK. 68 // <0 if NetEq returned an error. 69 // 70 int InsertPacket(const WebRtcRTPHeader& rtp_header, 71 rtc::ArrayView<const uint8_t> incoming_payload); 72 73 // 74 // Asks NetEq for 10 milliseconds of decoded audio. 75 // 76 // Input: 77 // -desired_freq_hz : specifies the sampling rate [Hz] of the output 78 // audio. If set -1 indicates to resampling is 79 // is required and the audio returned at the 80 // sampling rate of the decoder. 81 // 82 // Output: 83 // -audio_frame : an audio frame were output data and 84 // associated parameters are written to. 85 // 86 // Return value : 0 if OK. 87 // -1 if NetEq returned an error. 88 // 89 int GetAudio(int desired_freq_hz, AudioFrame* audio_frame); 90 91 // 92 // Adds a new codec to the NetEq codec database. 93 // 94 // Input: 95 // - acm_codec_id : ACM codec ID; -1 means external decoder. 96 // - payload_type : payload type. 97 // - sample_rate_hz : sample rate. 98 // - audio_decoder : pointer to a decoder object. If it's null, then 99 // NetEq will internally create a decoder object 100 // based on the value of |acm_codec_id| (which 101 // mustn't be -1). Otherwise, NetEq will use the 102 // given decoder for the given payload type. NetEq 103 // won't take ownership of the decoder; it's up to 104 // the caller to delete it when it's no longer 105 // needed. 106 // 107 // Providing an existing decoder object here is 108 // necessary for external decoders, but may also be 109 // used for built-in decoders if NetEq doesn't have 110 // all the info it needs to construct them properly 111 // (e.g. iSAC, where the decoder needs to be paired 112 // with an encoder). 113 // 114 // Return value : 0 if OK. 115 // <0 if NetEq returned an error. 116 // 117 int AddCodec(int acm_codec_id, 118 uint8_t payload_type, 119 size_t channels, 120 int sample_rate_hz, 121 AudioDecoder* audio_decoder, 122 const std::string& name); 123 124 // 125 // Sets a minimum delay for packet buffer. The given delay is maintained, 126 // unless channel condition dictates a higher delay. 127 // 128 // Input: 129 // - delay_ms : minimum delay in milliseconds. 130 // 131 // Return value : 0 if OK. 132 // <0 if NetEq returned an error. 133 // 134 int SetMinimumDelay(int delay_ms); 135 136 // 137 // Sets a maximum delay [ms] for the packet buffer. The target delay does not 138 // exceed the given value, even if channel condition requires so. 139 // 140 // Input: 141 // - delay_ms : maximum delay in milliseconds. 142 // 143 // Return value : 0 if OK. 144 // <0 if NetEq returned an error. 145 // 146 int SetMaximumDelay(int delay_ms); 147 148 // 149 // Get least required delay computed based on channel conditions. Note that 150 // this is before applying any user-defined limits (specified by calling 151 // (SetMinimumDelay() and/or SetMaximumDelay()). 152 // 153 int LeastRequiredDelayMs() const; 154 155 // 156 // Resets the initial delay to zero. 157 // 158 void ResetInitialDelay(); 159 160 // Returns the sample rate of the decoder associated with the last incoming 161 // packet. If no packet of a registered non-CNG codec has been received, the 162 // return value is empty. Also, if the decoder was unregistered since the last 163 // packet was inserted, the return value is empty. 164 rtc::Optional<int> last_packet_sample_rate_hz() const; 165 166 // Returns last_output_sample_rate_hz from the NetEq instance. 167 int last_output_sample_rate_hz() const; 168 169 // 170 // Get the current network statistics from NetEq. 171 // 172 // Output: 173 // - statistics : The current network statistics. 174 // 175 void GetNetworkStatistics(NetworkStatistics* statistics); 176 177 // 178 // Enable post-decoding VAD. 179 // 180 void EnableVad(); 181 182 // 183 // Disable post-decoding VAD. 184 // 185 void DisableVad(); 186 187 // 188 // Returns whether post-decoding VAD is enabled (true) or disabled (false). 189 // 190 bool vad_enabled() const { return vad_enabled_; } 191 192 // 193 // Flushes the NetEq packet and speech buffers. 194 // 195 void FlushBuffers(); 196 197 // 198 // Removes a payload-type from the NetEq codec database. 199 // 200 // Input: 201 // - payload_type : the payload-type to be removed. 202 // 203 // Return value : 0 if OK. 204 // -1 if an error occurred. 205 // 206 int RemoveCodec(uint8_t payload_type); 207 208 // 209 // Remove all registered codecs. 210 // 211 int RemoveAllCodecs(); 212 213 // 214 // Set ID. 215 // 216 void set_id(int id); // TODO(turajs): can be inline. 217 218 // 219 // Gets the RTP timestamp of the last sample delivered by GetAudio(). 220 // Returns true if the RTP timestamp is valid, otherwise false. 221 // 222 bool GetPlayoutTimestamp(uint32_t* timestamp); 223 224 // 225 // Get the audio codec associated with the last non-CNG/non-DTMF received 226 // payload. If no non-CNG/non-DTMF packet is received -1 is returned, 227 // otherwise return 0. 228 // 229 int LastAudioCodec(CodecInst* codec) const; 230 231 // 232 // Get a decoder given its registered payload-type. 233 // 234 // Input: 235 // -payload_type : the payload-type of the codec to be retrieved. 236 // 237 // Output: 238 // -codec : codec associated with the given payload-type. 239 // 240 // Return value : 0 if succeeded. 241 // -1 if failed, e.g. given payload-type is not 242 // registered. 243 // 244 int DecoderByPayloadType(uint8_t payload_type, 245 CodecInst* codec) const; 246 247 // 248 // Enable NACK and set the maximum size of the NACK list. If NACK is already 249 // enabled then the maximum NACK list size is modified accordingly. 250 // 251 // Input: 252 // -max_nack_list_size : maximum NACK list size 253 // should be positive (none zero) and less than or 254 // equal to |Nack::kNackListSizeLimit| 255 // Return value 256 // : 0 if succeeded. 257 // -1 if failed 258 // 259 int EnableNack(size_t max_nack_list_size); 260 261 // Disable NACK. 262 void DisableNack(); 263 264 // 265 // Get a list of packets to be retransmitted. 266 // 267 // Input: 268 // -round_trip_time_ms : estimate of the round-trip-time (in milliseconds). 269 // Return value : list of packets to be retransmitted. 270 // 271 std::vector<uint16_t> GetNackList(int64_t round_trip_time_ms) const; 272 273 // 274 // Get statistics of calls to GetAudio(). 275 void GetDecodingCallStatistics(AudioDecodingCallStats* stats) const; 276 277 private: 278 const Decoder* RtpHeaderToDecoder(const RTPHeader& rtp_header, 279 uint8_t payload_type) const 280 EXCLUSIVE_LOCKS_REQUIRED(crit_sect_); 281 282 uint32_t NowInTimestamp(int decoder_sampling_rate) const; 283 284 rtc::scoped_ptr<CriticalSectionWrapper> crit_sect_; 285 int id_; // TODO(henrik.lundin) Make const. 286 const Decoder* last_audio_decoder_ GUARDED_BY(crit_sect_); 287 AudioFrame::VADActivity previous_audio_activity_ GUARDED_BY(crit_sect_); 288 ACMResampler resampler_ GUARDED_BY(crit_sect_); 289 // Used in GetAudio, declared as member to avoid allocating every 10ms. 290 // TODO(henrik.lundin) Stack-allocate in GetAudio instead? 291 rtc::scoped_ptr<int16_t[]> audio_buffer_ GUARDED_BY(crit_sect_); 292 rtc::scoped_ptr<int16_t[]> last_audio_buffer_ GUARDED_BY(crit_sect_); 293 CallStatistics call_stats_ GUARDED_BY(crit_sect_); 294 NetEq* neteq_; 295 // Decoders map is keyed by payload type 296 std::map<uint8_t, Decoder> decoders_ GUARDED_BY(crit_sect_); 297 bool vad_enabled_; 298 Clock* clock_; // TODO(henrik.lundin) Make const if possible. 299 bool resampled_last_output_frame_ GUARDED_BY(crit_sect_); 300 rtc::Optional<int> last_packet_sample_rate_hz_ GUARDED_BY(crit_sect_); 301 }; 302 303 } // namespace acm2 304 305 } // namespace webrtc 306 307 #endif // WEBRTC_MODULES_AUDIO_CODING_ACM2_ACM_RECEIVER_H_ 308
