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 <map> 17 #include <memory> 18 #include <string> 19 #include <utility> 20 #include <vector> 21 22 #include "api/call/bitrate_allocation.h" 23 #include "api/sequence_checker.h" 24 #include "api/transport/network_types.h" 25 #include "rtc_base/system/no_unique_address.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 41 protected: ~BitrateAllocatorObserver()42 virtual ~BitrateAllocatorObserver() {} 43 }; 44 45 // Struct describing parameters for how a media stream should get bitrate 46 // allocated to it. 47 48 struct MediaStreamAllocationConfig { 49 // Minimum bitrate supported by track. 0 equals no min bitrate. 50 uint32_t min_bitrate_bps; 51 // Maximum bitrate supported by track. 0 equals no max bitrate. 52 uint32_t max_bitrate_bps; 53 uint32_t pad_up_bitrate_bps; 54 int64_t priority_bitrate_bps; 55 // True means track may not be paused by allocating 0 bitrate will allocate at 56 // least `min_bitrate_bps` for this observer, even if the BWE is too low, 57 // false will allocate 0 to the observer if BWE doesn't allow 58 // `min_bitrate_bps`. 59 bool enforce_min_bitrate; 60 // The amount of bitrate allocated to this observer relative to all other 61 // observers. If an observer has twice the bitrate_priority of other 62 // observers, it should be allocated twice the bitrate above its min. 63 double bitrate_priority; 64 }; 65 66 // Interface used for mocking 67 class BitrateAllocatorInterface { 68 public: 69 virtual void AddObserver(BitrateAllocatorObserver* observer, 70 MediaStreamAllocationConfig config) = 0; 71 virtual void RemoveObserver(BitrateAllocatorObserver* observer) = 0; 72 virtual int GetStartBitrate(BitrateAllocatorObserver* observer) const = 0; 73 74 protected: 75 virtual ~BitrateAllocatorInterface() = default; 76 }; 77 78 namespace bitrate_allocator_impl { 79 struct AllocatableTrack { AllocatableTrackAllocatableTrack80 AllocatableTrack(BitrateAllocatorObserver* observer, 81 MediaStreamAllocationConfig allocation_config) 82 : observer(observer), 83 config(allocation_config), 84 allocated_bitrate_bps(-1), 85 media_ratio(1.0) {} 86 BitrateAllocatorObserver* observer; 87 MediaStreamAllocationConfig config; 88 int64_t allocated_bitrate_bps; 89 double media_ratio; // Part of the total bitrate used for media [0.0, 1.0]. 90 91 uint32_t LastAllocatedBitrate() const; 92 // The minimum bitrate required by this observer, including 93 // enable-hysteresis if the observer is in a paused state. 94 uint32_t MinBitrateWithHysteresis() const; 95 }; 96 } // namespace bitrate_allocator_impl 97 98 // Usage: this class will register multiple RtcpBitrateObserver's one at each 99 // RTCP module. It will aggregate the results and run one bandwidth estimation 100 // and push the result to the encoders via BitrateAllocatorObserver(s). 101 class BitrateAllocator : public BitrateAllocatorInterface { 102 public: 103 // Used to get notified when send stream limits such as the minimum send 104 // bitrate and max padding bitrate is changed. 105 class LimitObserver { 106 public: 107 virtual void OnAllocationLimitsChanged(BitrateAllocationLimits limits) = 0; 108 109 protected: 110 virtual ~LimitObserver() = default; 111 }; 112 113 explicit BitrateAllocator(LimitObserver* limit_observer); 114 ~BitrateAllocator() override; 115 116 void UpdateStartRate(uint32_t start_rate_bps); 117 118 // Allocate target_bitrate across the registered BitrateAllocatorObservers. 119 void OnNetworkEstimateChanged(TargetTransferRate msg); 120 121 // Set the configuration used by the bandwidth management. 122 // `observer` updates bitrates if already in use. 123 // `config` is the configuration to use for allocation. 124 // Note that `observer`->OnBitrateUpdated() will be called 125 // within the scope of this method with the current rtt, fraction_loss and 126 // available bitrate and that the bitrate in OnBitrateUpdated will be zero if 127 // the `observer` is currently not allowed to send data. 128 void AddObserver(BitrateAllocatorObserver* observer, 129 MediaStreamAllocationConfig config) override; 130 131 // Removes a previously added observer, but will not trigger a new bitrate 132 // allocation. 133 void RemoveObserver(BitrateAllocatorObserver* observer) override; 134 135 // Returns initial bitrate allocated for `observer`. If `observer` is not in 136 // the list of added observers, a best guess is returned. 137 int GetStartBitrate(BitrateAllocatorObserver* observer) const override; 138 139 private: 140 using AllocatableTrack = bitrate_allocator_impl::AllocatableTrack; 141 142 // Calculates the minimum requested send bitrate and max padding bitrate and 143 // calls LimitObserver::OnAllocationLimitsChanged. 144 void UpdateAllocationLimits() RTC_RUN_ON(&sequenced_checker_); 145 146 // Allow packets to be transmitted in up to 2 times max video bitrate if the 147 // bandwidth estimate allows it. 148 // TODO(bugs.webrtc.org/8541): May be worth to refactor to keep this logic in 149 // video send stream. 150 static uint8_t GetTransmissionMaxBitrateMultiplier(); 151 152 RTC_NO_UNIQUE_ADDRESS SequenceChecker sequenced_checker_; 153 LimitObserver* const limit_observer_ RTC_GUARDED_BY(&sequenced_checker_); 154 // Stored in a list to keep track of the insertion order. 155 std::vector<AllocatableTrack> allocatable_tracks_ 156 RTC_GUARDED_BY(&sequenced_checker_); 157 uint32_t last_target_bps_ RTC_GUARDED_BY(&sequenced_checker_); 158 uint32_t last_stable_target_bps_ RTC_GUARDED_BY(&sequenced_checker_); 159 uint32_t last_non_zero_bitrate_bps_ RTC_GUARDED_BY(&sequenced_checker_); 160 uint8_t last_fraction_loss_ RTC_GUARDED_BY(&sequenced_checker_); 161 int64_t last_rtt_ RTC_GUARDED_BY(&sequenced_checker_); 162 int64_t last_bwe_period_ms_ RTC_GUARDED_BY(&sequenced_checker_); 163 // Number of mute events based on too low BWE, not network up/down. 164 int num_pause_events_ RTC_GUARDED_BY(&sequenced_checker_); 165 int64_t last_bwe_log_time_ RTC_GUARDED_BY(&sequenced_checker_); 166 BitrateAllocationLimits current_limits_ RTC_GUARDED_BY(&sequenced_checker_); 167 }; 168 169 } // namespace webrtc 170 #endif // CALL_BITRATE_ALLOCATOR_H_ 171