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(int 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;
BOOST_HOF_INHERIT_CONSTRUCTORboost::hof::detail::decorator_invoke102 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
base_functionboost::hof::detail::decorator_invoke111 // |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
get_decoratorboost::hof::detail::decorator_invoke117 // |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);
get_databoost::hof::detail::decorator_invoke123
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 int 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 DISALLOW_COPY_AND_ASSIGN(DelayManager);
161 };
162
BOOST_HOF_INHERIT_CONSTRUCTORboost::hof::detail::decoration163 } // namespace webrtc
164 #endif // WEBRTC_MODULES_AUDIO_CODING_NETEQ_DELAY_MANAGER_H_
165