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