1 /* 2 * Copyright (c) 2019 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 API_NETEQ_NETEQ_CONTROLLER_H_ 12 #define API_NETEQ_NETEQ_CONTROLLER_H_ 13 14 #include <cstddef> 15 #include <cstdint> 16 17 #include <functional> 18 #include <memory> 19 20 #include "absl/types/optional.h" 21 #include "api/neteq/neteq.h" 22 #include "api/neteq/tick_timer.h" 23 #include "system_wrappers/include/clock.h" 24 25 namespace webrtc { 26 27 // Decides the actions that NetEq should take. This affects the behavior of the 28 // jitter buffer, and how it reacts to network conditions. 29 // This class will undergo substantial refactoring in the near future, and the 30 // API is expected to undergo significant changes. A target API is given below: 31 // 32 // class NetEqController { 33 // public: 34 // // Resets object to a clean state. 35 // void Reset(); 36 // // Given NetEq status, make a decision. 37 // Operation GetDecision(NetEqStatus neteq_status); 38 // // Register every packet received. 39 // void RegisterPacket(PacketInfo packet_info); 40 // // Register empty packet. 41 // void RegisterEmptyPacket(); 42 // // Register a codec switching. 43 // void CodecSwithed(); 44 // // Sets the sample rate. 45 // void SetSampleRate(int fs_hz); 46 // // Sets the packet length in samples. 47 // void SetPacketLengthSamples(); 48 // // Sets maximum delay. 49 // void SetMaximumDelay(int delay_ms); 50 // // Sets mininum delay. 51 // void SetMinimumDelay(int delay_ms); 52 // // Sets base mininum delay. 53 // void SetBaseMinimumDelay(int delay_ms); 54 // // Gets target buffer level. 55 // int GetTargetBufferLevelMs() const; 56 // // Gets filtered buffer level. 57 // int GetFilteredBufferLevel() const; 58 // // Gets base minimum delay. 59 // int GetBaseMinimumDelay() const; 60 // } 61 62 class NetEqController { 63 public: 64 // This struct is used to create a NetEqController. 65 struct Config { 66 bool allow_time_stretching; 67 bool enable_rtx_handling; 68 int max_packets_in_buffer; 69 int base_min_delay_ms; 70 TickTimer* tick_timer; 71 webrtc::Clock* clock = nullptr; 72 }; 73 74 struct PacketInfo { 75 uint32_t timestamp; 76 bool is_dtx; 77 bool is_cng; 78 }; 79 80 struct PacketBufferInfo { 81 bool dtx_or_cng; 82 size_t num_samples; 83 size_t span_samples; 84 size_t span_samples_no_dtx; 85 size_t num_packets; 86 }; 87 88 struct NetEqStatus { 89 uint32_t target_timestamp; 90 int16_t expand_mutefactor; 91 size_t last_packet_samples; 92 absl::optional<PacketInfo> next_packet; 93 NetEq::Mode last_mode; 94 bool play_dtmf; 95 size_t generated_noise_samples; 96 PacketBufferInfo packet_buffer_info; 97 size_t sync_buffer_samples; 98 }; 99 100 virtual ~NetEqController() = default; 101 102 // Resets object to a clean state. 103 virtual void Reset() = 0; 104 105 // Resets parts of the state. Typically done when switching codecs. 106 virtual void SoftReset() = 0; 107 108 // Given info about the latest received packet, and current jitter buffer 109 // status, returns the operation. |target_timestamp| and |expand_mutefactor| 110 // are provided for reference. |last_packet_samples| is the number of samples 111 // obtained from the last decoded frame. If there is a packet available, it 112 // should be supplied in |packet|. The mode resulting from the last call to 113 // NetEqImpl::GetAudio is supplied in |last_mode|. If there is a DTMF event to 114 // play, |play_dtmf| should be set to true. The output variable 115 // |reset_decoder| will be set to true if a reset is required; otherwise it is 116 // left unchanged (i.e., it can remain true if it was true before the call). 117 virtual NetEq::Operation GetDecision(const NetEqStatus& status, 118 bool* reset_decoder) = 0; 119 120 // Inform NetEqController that an empty packet has arrived. 121 virtual void RegisterEmptyPacket() = 0; 122 123 // Sets the sample rate and the output block size. 124 virtual void SetSampleRate(int fs_hz, size_t output_size_samples) = 0; 125 126 // Sets a minimum or maximum delay in millisecond. 127 // Returns true if the delay bound is successfully applied, otherwise false. 128 virtual bool SetMaximumDelay(int delay_ms) = 0; 129 virtual bool SetMinimumDelay(int delay_ms) = 0; 130 131 // Sets a base minimum delay in milliseconds for packet buffer. The effective 132 // minimum delay can't be lower than base minimum delay, even if a lower value 133 // is set using SetMinimumDelay. 134 // Returns true if the base minimum is successfully applied, otherwise false. 135 virtual bool SetBaseMinimumDelay(int delay_ms) = 0; 136 virtual int GetBaseMinimumDelay() const = 0; 137 138 // These methods test the |cng_state_| for different conditions. 139 virtual bool CngRfc3389On() const = 0; 140 virtual bool CngOff() const = 0; 141 142 // Resets the |cng_state_| to kCngOff. 143 virtual void SetCngOff() = 0; 144 145 // Reports back to DecisionLogic whether the decision to do expand remains or 146 // not. Note that this is necessary, since an expand decision can be changed 147 // to kNormal in NetEqImpl::GetDecision if there is still enough data in the 148 // sync buffer. 149 virtual void ExpandDecision(NetEq::Operation operation) = 0; 150 151 // Adds |value| to |sample_memory_|. 152 virtual void AddSampleMemory(int32_t value) = 0; 153 154 // Returns the target buffer level in ms. 155 virtual int TargetLevelMs() = 0; 156 157 // Notify the NetEqController that a packet has arrived. Returns the relative 158 // arrival delay, if it can be computed. 159 virtual absl::optional<int> PacketArrived(bool last_cng_or_dtmf, 160 size_t packet_length_samples, 161 bool should_update_stats, 162 uint16_t main_sequence_number, 163 uint32_t main_timestamp, 164 int fs_hz) = 0; 165 166 // Returns true if a peak was found. 167 virtual bool PeakFound() const = 0; 168 169 // Get the filtered buffer level in samples. 170 virtual int GetFilteredBufferLevel() const = 0; 171 172 // Accessors and mutators. 173 virtual void set_sample_memory(int32_t value) = 0; 174 virtual size_t noise_fast_forward() const = 0; 175 virtual size_t packet_length_samples() const = 0; 176 virtual void set_packet_length_samples(size_t value) = 0; 177 virtual void set_prev_time_scale(bool value) = 0; 178 }; 179 180 } // namespace webrtc 181 #endif // API_NETEQ_NETEQ_CONTROLLER_H_ 182