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_NETEQ_DELAY_MANAGER_H_ 12 #define WEBRTC_MODULES_AUDIO_CODING_NETEQ_DELAY_MANAGER_H_ 13 14 #include <string.h> // Provide access to size_t. 15 16 #include <vector> 17 18 #include "webrtc/base/constructormagic.h" 19 #include "webrtc/modules/audio_coding/neteq/audio_decoder_impl.h" 20 #include "webrtc/typedefs.h" 21 22 namespace webrtc { 23 24 // Forward declaration. 25 class DelayPeakDetector; 26 27 class DelayManager { 28 public: 29 typedef std::vector<int> IATVector; 30 31 // Create a DelayManager object. Notify the delay manager that the packet 32 // buffer can hold no more than |max_packets_in_buffer| packets (i.e., this 33 // is the number of packet slots in the buffer). Supply a PeakDetector 34 // object to the DelayManager. 35 DelayManager(size_t max_packets_in_buffer, DelayPeakDetector* peak_detector); 36 37 virtual ~DelayManager(); 38 39 // Read the inter-arrival time histogram. Mainly for testing purposes. 40 virtual const IATVector& iat_vector() const; 41 42 // Updates the delay manager with a new incoming packet, with 43 // |sequence_number| and |timestamp| from the RTP header. This updates the 44 // inter-arrival time histogram and other statistics, as well as the 45 // associated DelayPeakDetector. A new target buffer level is calculated. 46 // Returns 0 on success, -1 on failure (invalid sample rate). 47 virtual int Update(uint16_t sequence_number, 48 uint32_t timestamp, 49 int sample_rate_hz); 50 51 // Calculates a new target buffer level. Called from the Update() method. 52 // Sets target_level_ (in Q8) and returns the same value. Also calculates 53 // and updates base_target_level_, which is the target buffer level before 54 // taking delay peaks into account. 55 virtual int CalculateTargetLevel(int iat_packets); 56 57 // Notifies the DelayManager of how much audio data is carried in each packet. 58 // The method updates the DelayPeakDetector too, and resets the inter-arrival 59 // time counter. Returns 0 on success, -1 on failure. 60 virtual int SetPacketAudioLength(int length_ms); 61 62 // Resets the DelayManager and the associated DelayPeakDetector. 63 virtual void Reset(); 64 65 // Calculates the average inter-arrival time deviation from the histogram. 66 // The result is returned as parts-per-million deviation from the nominal 67 // inter-arrival time. That is, if the average inter-arrival time is equal to 68 // the nominal frame time, the return value is zero. A positive value 69 // corresponds to packet spacing being too large, while a negative value means 70 // that the packets arrive with less spacing than expected. 71 virtual int AverageIAT() const; 72 73 // Returns true if peak-mode is active. That is, delay peaks were observed 74 // recently. This method simply asks for the same information from the 75 // DelayPeakDetector object. 76 virtual bool PeakFound() const; 77 78 // Notifies the counters in DelayManager and DelayPeakDetector that 79 // |elapsed_time_ms| have elapsed. 80 virtual void UpdateCounters(int elapsed_time_ms); 81 82 // Reset the inter-arrival time counter to 0. 83 virtual void ResetPacketIatCount(); 84 85 // Writes the lower and higher limits which the buffer level should stay 86 // within to the corresponding pointers. The values are in (fractions of) 87 // packets in Q8. 88 virtual void BufferLimits(int* lower_limit, int* higher_limit) const; 89 90 // Gets the target buffer level, in (fractions of) packets in Q8. This value 91 // includes any extra delay set through the set_extra_delay_ms() method. 92 virtual int TargetLevel() const; 93 94 virtual void LastDecoderType(NetEqDecoder decoder_type); 95 96 // Accessors and mutators. 97 // Assuming |delay| is in valid range. 98 virtual bool SetMinimumDelay(int delay_ms); 99 virtual bool SetMaximumDelay(int delay_ms); 100 virtual int least_required_delay_ms() const; 101 virtual int base_target_level() const; 102 virtual void set_streaming_mode(bool value); 103 virtual int last_pack_cng_or_dtmf() const; 104 virtual void set_last_pack_cng_or_dtmf(int value); 105 106 private: 107 static const int kLimitProbability = 53687091; // 1/20 in Q30. 108 static const int kLimitProbabilityStreaming = 536871; // 1/2000 in Q30. 109 static const int kMaxStreamingPeakPeriodMs = 600000; // 10 minutes in ms. 110 static const int kCumulativeSumDrift = 2; // Drift term for cumulative sum 111 // |iat_cumulative_sum_|. 112 // Steady-state forgetting factor for |iat_vector_|, 0.9993 in Q15. 113 static const int kIatFactor_ = 32745; 114 static const int kMaxIat = 64; // Max inter-arrival time to register. 115 116 // Sets |iat_vector_| to the default start distribution and sets the 117 // |base_target_level_| and |target_level_| to the corresponding values. 118 void ResetHistogram(); 119 120 // Updates |iat_cumulative_sum_| and |max_iat_cumulative_sum_|. (These are 121 // used by the streaming mode.) This method is called by Update(). 122 void UpdateCumulativeSums(int packet_len_ms, uint16_t sequence_number); 123 124 // Updates the histogram |iat_vector_|. The probability for inter-arrival time 125 // equal to |iat_packets| (in integer packets) is increased slightly, while 126 // all other entries are decreased. This method is called by Update(). 127 void UpdateHistogram(size_t iat_packets); 128 129 // Makes sure that |target_level_| is not too large, taking 130 // |max_packets_in_buffer_| and |extra_delay_ms_| into account. This method is 131 // called by Update(). 132 void LimitTargetLevel(); 133 134 bool first_packet_received_; 135 const size_t max_packets_in_buffer_; // Capacity of the packet buffer. 136 IATVector iat_vector_; // Histogram of inter-arrival times. 137 int iat_factor_; // Forgetting factor for updating the IAT histogram (Q15). 138 int packet_iat_count_ms_; // Milliseconds elapsed since last packet. 139 int base_target_level_; // Currently preferred buffer level before peak 140 // detection and streaming mode (Q0). 141 // TODO(turajs) change the comment according to the implementation of 142 // minimum-delay. 143 int target_level_; // Currently preferred buffer level in (fractions) 144 // of packets (Q8), before adding any extra delay. 145 int packet_len_ms_; // Length of audio in each incoming packet [ms]. 146 bool streaming_mode_; 147 uint16_t last_seq_no_; // Sequence number for last received packet. 148 uint32_t last_timestamp_; // Timestamp for the last received packet. 149 int minimum_delay_ms_; // Externally set minimum delay. 150 int least_required_delay_ms_; // Smallest preferred buffer level (same unit 151 // as |target_level_|), before applying 152 // |minimum_delay_ms_| and/or |maximum_delay_ms_|. 153 int maximum_delay_ms_; // Externally set maximum allowed delay. 154 int iat_cumulative_sum_; // Cumulative sum of delta inter-arrival times. 155 int max_iat_cumulative_sum_; // Max of |iat_cumulative_sum_|. 156 int max_timer_ms_; // Time elapsed since maximum was observed. 157 DelayPeakDetector& peak_detector_; 158 int last_pack_cng_or_dtmf_; 159 160 RTC_DISALLOW_COPY_AND_ASSIGN(DelayManager); 161 }; 162 163 } // namespace webrtc 164 #endif // WEBRTC_MODULES_AUDIO_CODING_NETEQ_DELAY_MANAGER_H_ 165