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 MODULES_AUDIO_CODING_NETEQ_DELAY_MANAGER_H_
12 #define MODULES_AUDIO_CODING_NETEQ_DELAY_MANAGER_H_
13 
14 #include <string.h>  // Provide access to size_t.
15 
16 #include <deque>
17 #include <memory>
18 
19 #include "absl/types/optional.h"
20 #include "api/neteq/tick_timer.h"
21 #include "modules/audio_coding/neteq/histogram.h"
22 #include "rtc_base/constructor_magic.h"
23 
24 namespace webrtc {
25 
26 class DelayManager {
27  public:
28   DelayManager(size_t max_packets_in_buffer,
29                int base_minimum_delay_ms,
30                int histogram_quantile,
31                bool enable_rtx_handling,
32                const TickTimer* tick_timer,
33                std::unique_ptr<Histogram> histogram);
34 
35   // Create a DelayManager object. Notify the delay manager that the packet
36   // buffer can hold no more than |max_packets_in_buffer| packets (i.e., this
37   // is the number of packet slots in the buffer) and that the target delay
38   // should be greater than or equal to |base_minimum_delay_ms|. Supply a
39   // PeakDetector object to the DelayManager.
40   static std::unique_ptr<DelayManager> Create(size_t max_packets_in_buffer,
41                                               int base_minimum_delay_ms,
42                                               bool enable_rtx_handling,
43                                               const TickTimer* tick_timer);
44 
45   virtual ~DelayManager();
46 
47   // Updates the delay manager with a new incoming packet, with
48   // |sequence_number| and |timestamp| from the RTP header. This updates the
49   // inter-arrival time histogram and other statistics, as well as the
50   // associated DelayPeakDetector. A new target buffer level is calculated.
51   // Returns the relative delay if it can be calculated.
52   virtual absl::optional<int> Update(uint16_t sequence_number,
53                                      uint32_t timestamp,
54                                      int sample_rate_hz);
55 
56   // Calculates a new target buffer level. Called from the Update() method.
57   // Sets target_level_ (in Q8) and returns the same value. Also calculates
58   // and updates base_target_level_, which is the target buffer level before
59   // taking delay peaks into account.
60   virtual int CalculateTargetLevel();
61 
62   // Notifies the DelayManager of how much audio data is carried in each packet.
63   // The method updates the DelayPeakDetector too, and resets the inter-arrival
64   // time counter. Returns 0 on success, -1 on failure.
65   virtual int SetPacketAudioLength(int length_ms);
66 
67   // Resets the DelayManager and the associated DelayPeakDetector.
68   virtual void Reset();
69 
70   // Reset the inter-arrival time counter to 0.
71   virtual void ResetPacketIatCount();
72 
73   // Writes the lower and higher limits which the buffer level should stay
74   // within to the corresponding pointers. The values are in (fractions of)
75   // packets in Q8.
76   virtual void BufferLimits(int* lower_limit, int* higher_limit) const;
77   virtual void BufferLimits(int target_level,
78                             int* lower_limit,
79                             int* higher_limit) const;
80 
81   // Gets the target buffer level, in (fractions of) packets in Q8.
82   virtual int TargetLevel() const;
83 
84   // Informs the delay manager whether or not the last decoded packet contained
85   // speech.
86   virtual void LastDecodedWasCngOrDtmf(bool it_was);
87 
88   // Notify the delay manager that empty packets have been received. These are
89   // packets that are part of the sequence number series, so that an empty
90   // packet will shift the sequence numbers for the following packets.
91   virtual void RegisterEmptyPacket();
92 
93   // Accessors and mutators.
94   // Assuming |delay| is in valid range.
95   virtual bool SetMinimumDelay(int delay_ms);
96   virtual bool SetMaximumDelay(int delay_ms);
97   virtual bool SetBaseMinimumDelay(int delay_ms);
98   virtual int GetBaseMinimumDelay() const;
99   virtual int base_target_level() const;
100   virtual int last_pack_cng_or_dtmf() const;
101   virtual void set_last_pack_cng_or_dtmf(int value);
102 
103   // This accessor is only intended for testing purposes.
effective_minimum_delay_ms_for_test()104   int effective_minimum_delay_ms_for_test() const {
105     return effective_minimum_delay_ms_;
106   }
107 
108   // These accessors are only intended for testing purposes.
histogram_quantile()109   int histogram_quantile() const { return histogram_quantile_; }
histogram()110   Histogram* histogram() const { return histogram_.get(); }
111 
112  private:
113   // Provides value which minimum delay can't exceed based on current buffer
114   // size and given |maximum_delay_ms_|. Lower bound is a constant 0.
115   int MinimumDelayUpperBound() const;
116 
117   // Provides 75% of currently possible maximum buffer size in milliseconds.
118   int MaxBufferTimeQ75() const;
119 
120   // Updates |delay_history_|.
121   void UpdateDelayHistory(int iat_delay_ms,
122                           uint32_t timestamp,
123                           int sample_rate_hz);
124 
125   // Calculate relative packet arrival delay from |delay_history_|.
126   int CalculateRelativePacketArrivalDelay() const;
127 
128   // Updates |effective_minimum_delay_ms_| delay based on current
129   // |minimum_delay_ms_|, |base_minimum_delay_ms_| and |maximum_delay_ms_|
130   // and buffer size.
131   void UpdateEffectiveMinimumDelay();
132 
133   // Makes sure that |target_level_| is not too large, taking
134   // |max_packets_in_buffer_| into account. This method is called by Update().
135   void LimitTargetLevel();
136 
137   // Makes sure that |delay_ms| is less than maximum delay, if any maximum
138   // is set. Also, if possible check |delay_ms| to be less than 75% of
139   // |max_packets_in_buffer_|.
140   bool IsValidMinimumDelay(int delay_ms) const;
141 
142   bool IsValidBaseMinimumDelay(int delay_ms) const;
143 
144   bool first_packet_received_;
145   const size_t max_packets_in_buffer_;  // Capacity of the packet buffer.
146   std::unique_ptr<Histogram> histogram_;
147   const int histogram_quantile_;
148   const TickTimer* tick_timer_;
149   int base_minimum_delay_ms_;
150   // Provides delay which is used by LimitTargetLevel as lower bound on target
151   // delay.
152   int effective_minimum_delay_ms_;
153 
154   // Time elapsed since last packet.
155   std::unique_ptr<TickTimer::Stopwatch> packet_iat_stopwatch_;
156   int base_target_level_;  // Currently preferred buffer level before peak
157                            // detection and streaming mode (Q0).
158   // TODO(turajs) change the comment according to the implementation of
159   // minimum-delay.
160   int target_level_;         // Currently preferred buffer level in (fractions)
161                              // of packets (Q8), before adding any extra delay.
162   int packet_len_ms_;        // Length of audio in each incoming packet [ms].
163   uint16_t last_seq_no_;     // Sequence number for last received packet.
164   uint32_t last_timestamp_;  // Timestamp for the last received packet.
165   int minimum_delay_ms_;     // Externally set minimum delay.
166   int maximum_delay_ms_;     // Externally set maximum allowed delay.
167   int last_pack_cng_or_dtmf_;
168   const bool enable_rtx_handling_;
169   int num_reordered_packets_ = 0;  // Number of consecutive reordered packets.
170 
171   struct PacketDelay {
172     int iat_delay_ms;
173     uint32_t timestamp;
174   };
175   std::deque<PacketDelay> delay_history_;
176 
177   RTC_DISALLOW_COPY_AND_ASSIGN(DelayManager);
178 };
179 
180 }  // namespace webrtc
181 #endif  // MODULES_AUDIO_CODING_NETEQ_DELAY_MANAGER_H_
182