bitrate_allocator.h (7823B)
1 /* 2 * Copyright (c) 2015 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 CALL_BITRATE_ALLOCATOR_H_ 12 #define CALL_BITRATE_ALLOCATOR_H_ 13 14 #include <stdint.h> 15 16 #include <optional> 17 #include <vector> 18 19 #include "api/call/bitrate_allocation.h" 20 #include "api/field_trials_view.h" 21 #include "api/sequence_checker.h" 22 #include "api/transport/network_types.h" 23 #include "api/units/data_rate.h" 24 #include "rtc_base/system/no_unique_address.h" 25 #include "rtc_base/thread_annotations.h" 26 27 namespace webrtc { 28 29 class Clock; 30 31 // Used by all send streams with adaptive bitrate, to get the currently 32 // allocated bitrate for the send stream. The current network properties are 33 // given at the same time, to let the send stream decide about possible loss 34 // protection. 35 class BitrateAllocatorObserver { 36 public: 37 // Returns the amount of protection used by the BitrateAllocatorObserver 38 // implementation, as bitrate in bps. 39 virtual uint32_t OnBitrateUpdated(BitrateAllocationUpdate update) = 0; 40 // Returns the bitrate consumed (vs allocated) by BitrateAllocatorObserver 41 virtual std::optional<DataRate> GetUsedRate() const = 0; 42 43 protected: 44 virtual ~BitrateAllocatorObserver() {} 45 }; 46 47 // Struct describing parameters for how a media stream should get bitrate 48 // allocated to it. 49 50 enum class TrackRateElasticity { 51 kCanContributeUnusedRate, 52 kCanConsumeExtraRate, 53 kCanContributeAndConsume 54 }; 55 56 struct MediaStreamAllocationConfig { 57 // Minimum bitrate supported by track. 0 equals no min bitrate. 58 uint32_t min_bitrate_bps; 59 // Maximum bitrate supported by track. 0 equals no max bitrate. 60 uint32_t max_bitrate_bps; 61 uint32_t pad_up_bitrate_bps; 62 int64_t priority_bitrate_bps; 63 // True means track may not be paused by allocating 0 bitrate will allocate at 64 // least `min_bitrate_bps` for this observer, even if the BWE is too low, 65 // false will allocate 0 to the observer if BWE doesn't allow 66 // `min_bitrate_bps`. 67 bool enforce_min_bitrate; 68 // The amount of bitrate allocated to this observer relative to all other 69 // observers. If an observer has twice the bitrate_priority of other 70 // observers, it should be allocated twice the bitrate above its min. 71 double bitrate_priority; 72 std::optional<TrackRateElasticity> rate_elasticity; 73 }; 74 75 // Interface used for mocking 76 class BitrateAllocatorInterface { 77 public: 78 virtual void AddObserver(BitrateAllocatorObserver* observer, 79 MediaStreamAllocationConfig config) = 0; 80 virtual void RemoveObserver(BitrateAllocatorObserver* observer) = 0; 81 virtual int GetStartBitrate(BitrateAllocatorObserver* observer) const = 0; 82 83 protected: 84 virtual ~BitrateAllocatorInterface() = default; 85 }; 86 87 namespace bitrate_allocator_impl { 88 struct AllocatableTrack { 89 AllocatableTrack(BitrateAllocatorObserver* observer, 90 MediaStreamAllocationConfig allocation_config) 91 : observer(observer), 92 config(allocation_config), 93 allocated_bitrate_bps(-1), 94 media_ratio(1.0) {} 95 BitrateAllocatorObserver* observer; 96 MediaStreamAllocationConfig config; 97 int64_t allocated_bitrate_bps; 98 std::optional<DataRate> last_used_bitrate; 99 double media_ratio; // Part of the total bitrate used for media [0.0, 1.0]. 100 101 uint32_t LastAllocatedBitrate() const; 102 // The minimum bitrate required by this observer, including 103 // enable-hysteresis if the observer is in a paused state. 104 uint32_t MinBitrateWithHysteresis() const; 105 }; 106 } // namespace bitrate_allocator_impl 107 108 // Usage: this class will register multiple RtcpBitrateObserver's one at each 109 // RTCP module. It will aggregate the results and run one bandwidth estimation 110 // and push the result to the encoders via BitrateAllocatorObserver(s). 111 class BitrateAllocator : public BitrateAllocatorInterface { 112 public: 113 // Used to get notified when send stream limits such as the minimum send 114 // bitrate and max padding bitrate is changed. 115 class LimitObserver { 116 public: 117 virtual void OnAllocationLimitsChanged(BitrateAllocationLimits limits) = 0; 118 119 protected: 120 virtual ~LimitObserver() = default; 121 }; 122 123 // `upper_elastic_rate_limit` specifies the rate ceiling an observer can 124 // reach when unused bits are added. A value of zero disables borrowing of 125 // unused rates. 126 BitrateAllocator(LimitObserver* limit_observer, 127 DataRate upper_elastic_rate_limit); 128 ~BitrateAllocator() override; 129 130 void UpdateStartRate(uint32_t start_rate_bps); 131 132 // Allocate target_bitrate across the registered BitrateAllocatorObservers. 133 void OnNetworkEstimateChanged(TargetTransferRate msg); 134 135 // Set the configuration used by the bandwidth management. 136 // `observer` updates bitrates if already in use. 137 // `config` is the configuration to use for allocation. 138 // Note that `observer`->OnBitrateUpdated() will be called 139 // within the scope of this method with the current rtt, fraction_loss and 140 // available bitrate and that the bitrate in OnBitrateUpdated will be zero if 141 // the `observer` is currently not allowed to send data. 142 void AddObserver(BitrateAllocatorObserver* observer, 143 MediaStreamAllocationConfig config) override; 144 145 // Checks and recomputes bitrate allocation if necessary (when an 146 // elastic/audio bitrate increases significantly). Returns whether there is an 147 // active contributing and active consuming stream. 148 bool RecomputeAllocationIfNeeded(); 149 150 // Removes a previously added observer, but will not trigger a new bitrate 151 // allocation. 152 void RemoveObserver(BitrateAllocatorObserver* observer) override; 153 154 // Returns initial bitrate allocated for `observer`. If `observer` is not in 155 // the list of added observers, a best guess is returned. 156 int GetStartBitrate(BitrateAllocatorObserver* observer) const override; 157 158 private: 159 using AllocatableTrack = bitrate_allocator_impl::AllocatableTrack; 160 161 // Calculates the minimum requested send bitrate and max padding bitrate and 162 // calls LimitObserver::OnAllocationLimitsChanged. 163 void UpdateAllocationLimits() RTC_RUN_ON(&sequenced_checker_); 164 165 // Allow packets to be transmitted in up to 2 times max video bitrate if the 166 // bandwidth estimate allows it. 167 // TODO(bugs.webrtc.org/8541): May be worth to refactor to keep this logic in 168 // video send stream. 169 static uint8_t GetTransmissionMaxBitrateMultiplier(); 170 171 RTC_NO_UNIQUE_ADDRESS SequenceChecker sequenced_checker_; 172 LimitObserver* const limit_observer_ RTC_GUARDED_BY(&sequenced_checker_); 173 // Stored in a list to keep track of the insertion order. 174 std::vector<AllocatableTrack> allocatable_tracks_ 175 RTC_GUARDED_BY(&sequenced_checker_); 176 uint32_t last_target_bps_ RTC_GUARDED_BY(&sequenced_checker_); 177 uint32_t last_non_zero_bitrate_bps_ RTC_GUARDED_BY(&sequenced_checker_); 178 uint8_t last_fraction_loss_ RTC_GUARDED_BY(&sequenced_checker_); 179 int64_t last_rtt_ RTC_GUARDED_BY(&sequenced_checker_); 180 int64_t last_bwe_period_ms_ RTC_GUARDED_BY(&sequenced_checker_); 181 // Number of mute events based on too low BWE, not network up/down. 182 int num_pause_events_ RTC_GUARDED_BY(&sequenced_checker_); 183 int64_t last_bwe_log_time_ RTC_GUARDED_BY(&sequenced_checker_); 184 BitrateAllocationLimits current_limits_ RTC_GUARDED_BY(&sequenced_checker_); 185 const DataRate upper_elastic_rate_limit_ RTC_GUARDED_BY(&sequenced_checker_); 186 }; 187 188 // TODO(b/350555527): Remove after experiment 189 DataRate GetElasticRateAllocationFieldTrialParameter( 190 const FieldTrialsView& field_trials); 191 192 } // namespace webrtc 193 #endif // CALL_BITRATE_ALLOCATOR_H_