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
22namespace webrtc {
23
24// Forward declaration.
25class DelayPeakDetector;
26
27class 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