• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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