blob: b7d77d9fb2bfce87bbf5cbd3741183d63d14f9e2 [file] [log] [blame]
/*
* Copyright (c) 2015 The WebRTC project authors. All Rights Reserved.
*
* Use of this source code is governed by a BSD-style license
* that can be found in the LICENSE file in the root of the source
* tree. An additional intellectual property rights grant can be found
* in the file PATENTS. All contributing project authors may
* be found in the AUTHORS file in the root of the source tree.
*/
#ifndef CALL_BITRATE_ALLOCATOR_H_
#define CALL_BITRATE_ALLOCATOR_H_
#include <stdint.h>
#include <map>
#include <memory>
#include <string>
#include <utility>
#include <vector>
#include "api/call/bitrate_allocation.h"
#include "api/transport/network_types.h"
#include "rtc_base/synchronization/sequence_checker.h"
namespace webrtc {
class Clock;
// Used by all send streams with adaptive bitrate, to get the currently
// allocated bitrate for the send stream. The current network properties are
// given at the same time, to let the send stream decide about possible loss
// protection.
class BitrateAllocatorObserver {
public:
// Returns the amount of protection used by the BitrateAllocatorObserver
// implementation, as bitrate in bps.
virtual uint32_t OnBitrateUpdated(BitrateAllocationUpdate update) = 0;
protected:
virtual ~BitrateAllocatorObserver() {}
};
// Struct describing parameters for how a media stream should get bitrate
// allocated to it.
struct MediaStreamAllocationConfig {
// Minimum bitrate supported by track. 0 equals no min bitrate.
uint32_t min_bitrate_bps;
// Maximum bitrate supported by track. 0 equals no max bitrate.
uint32_t max_bitrate_bps;
uint32_t pad_up_bitrate_bps;
int64_t priority_bitrate_bps;
// True means track may not be paused by allocating 0 bitrate will allocate at
// least |min_bitrate_bps| for this observer, even if the BWE is too low,
// false will allocate 0 to the observer if BWE doesn't allow
// |min_bitrate_bps|.
bool enforce_min_bitrate;
// The amount of bitrate allocated to this observer relative to all other
// observers. If an observer has twice the bitrate_priority of other
// observers, it should be allocated twice the bitrate above its min.
double bitrate_priority;
};
// Interface used for mocking
class BitrateAllocatorInterface {
public:
virtual void AddObserver(BitrateAllocatorObserver* observer,
MediaStreamAllocationConfig config) = 0;
virtual void RemoveObserver(BitrateAllocatorObserver* observer) = 0;
virtual int GetStartBitrate(BitrateAllocatorObserver* observer) const = 0;
protected:
virtual ~BitrateAllocatorInterface() = default;
};
// Usage: this class will register multiple RtcpBitrateObserver's one at each
// RTCP module. It will aggregate the results and run one bandwidth estimation
// and push the result to the encoders via BitrateAllocatorObserver(s).
class BitrateAllocator : public BitrateAllocatorInterface {
public:
// Used to get notified when send stream limits such as the minimum send
// bitrate and max padding bitrate is changed.
class LimitObserver {
public:
virtual void OnAllocationLimitsChanged(BitrateAllocationLimits limits) = 0;
protected:
virtual ~LimitObserver() = default;
};
explicit BitrateAllocator(LimitObserver* limit_observer);
~BitrateAllocator() override;
void UpdateStartRate(uint32_t start_rate_bps);
// Allocate target_bitrate across the registered BitrateAllocatorObservers.
void OnNetworkEstimateChanged(TargetTransferRate msg);
// Set the configuration used by the bandwidth management.
// |observer| updates bitrates if already in use.
// |config| is the configuration to use for allocation.
// Note that |observer|->OnBitrateUpdated() will be called
// within the scope of this method with the current rtt, fraction_loss and
// available bitrate and that the bitrate in OnBitrateUpdated will be zero if
// the |observer| is currently not allowed to send data.
void AddObserver(BitrateAllocatorObserver* observer,
MediaStreamAllocationConfig config) override;
// Removes a previously added observer, but will not trigger a new bitrate
// allocation.
void RemoveObserver(BitrateAllocatorObserver* observer) override;
// Returns initial bitrate allocated for |observer|. If |observer| is not in
// the list of added observers, a best guess is returned.
int GetStartBitrate(BitrateAllocatorObserver* observer) const override;
private:
struct AllocatableTrack {
AllocatableTrack(BitrateAllocatorObserver* observer,
MediaStreamAllocationConfig allocation_config)
: observer(observer),
config(allocation_config),
allocated_bitrate_bps(-1),
media_ratio(1.0) {}
BitrateAllocatorObserver* observer;
MediaStreamAllocationConfig config;
int64_t allocated_bitrate_bps;
double media_ratio; // Part of the total bitrate used for media [0.0, 1.0].
uint32_t LastAllocatedBitrate() const;
// The minimum bitrate required by this observer, including
// enable-hysteresis if the observer is in a paused state.
uint32_t MinBitrateWithHysteresis() const;
};
// Calculates the minimum requested send bitrate and max padding bitrate and
// calls LimitObserver::OnAllocationLimitsChanged.
void UpdateAllocationLimits() RTC_RUN_ON(&sequenced_checker_);
typedef std::multimap<uint32_t, const AllocatableTrack*> ObserverSortingMap;
typedef std::map<BitrateAllocatorObserver*, int> ObserverAllocation;
ObserverAllocation AllocateBitrates(uint32_t bitrate) const
RTC_RUN_ON(&sequenced_checker_);
// Allocates zero bitrate to all observers.
ObserverAllocation ZeroRateAllocation() const RTC_RUN_ON(&sequenced_checker_);
// Allocates bitrate to observers when there isn't enough to allocate the
// minimum to all observers.
ObserverAllocation LowRateAllocation(uint32_t bitrate) const
RTC_RUN_ON(&sequenced_checker_);
// Allocates bitrate to all observers when the available bandwidth is enough
// to allocate the minimum to all observers but not enough to allocate the
// max bitrate of each observer.
ObserverAllocation NormalRateAllocation(uint32_t bitrate,
uint32_t sum_min_bitrates) const
RTC_RUN_ON(&sequenced_checker_);
// Allocates bitrate to observers when there is enough available bandwidth
// for all observers to be allocated their max bitrate.
ObserverAllocation MaxRateAllocation(uint32_t bitrate,
uint32_t sum_max_bitrates) const
RTC_RUN_ON(&sequenced_checker_);
// Splits |bitrate| evenly to observers already in |allocation|.
// |include_zero_allocations| decides if zero allocations should be part of
// the distribution or not. The allowed max bitrate is |max_multiplier| x
// observer max bitrate.
void DistributeBitrateEvenly(uint32_t bitrate,
bool include_zero_allocations,
int max_multiplier,
ObserverAllocation* allocation) const
RTC_RUN_ON(&sequenced_checker_);
bool EnoughBitrateForAllObservers(uint32_t bitrate,
uint32_t sum_min_bitrates) const
RTC_RUN_ON(&sequenced_checker_);
// From the available |bitrate|, each observer will be allocated a
// proportional amount based upon its bitrate priority. If that amount is
// more than the observer's capacity, it will be allocated its capacity, and
// the excess bitrate is still allocated proportionally to other observers.
// Allocating the proportional amount means an observer with twice the
// bitrate_priority of another will be allocated twice the bitrate.
void DistributeBitrateRelatively(
uint32_t bitrate,
const ObserverAllocation& observers_capacities,
ObserverAllocation* allocation) const RTC_RUN_ON(&sequenced_checker_);
// Allow packets to be transmitted in up to 2 times max video bitrate if the
// bandwidth estimate allows it.
// TODO(bugs.webrtc.org/8541): May be worth to refactor to keep this logic in
// video send stream.
static uint8_t GetTransmissionMaxBitrateMultiplier();
SequenceChecker sequenced_checker_;
LimitObserver* const limit_observer_ RTC_GUARDED_BY(&sequenced_checker_);
// Stored in a list to keep track of the insertion order.
std::vector<AllocatableTrack> allocatable_tracks_
RTC_GUARDED_BY(&sequenced_checker_);
uint32_t last_target_bps_ RTC_GUARDED_BY(&sequenced_checker_);
uint32_t last_stable_target_bps_ RTC_GUARDED_BY(&sequenced_checker_);
uint32_t last_non_zero_bitrate_bps_ RTC_GUARDED_BY(&sequenced_checker_);
uint8_t last_fraction_loss_ RTC_GUARDED_BY(&sequenced_checker_);
int64_t last_rtt_ RTC_GUARDED_BY(&sequenced_checker_);
int64_t last_bwe_period_ms_ RTC_GUARDED_BY(&sequenced_checker_);
// Number of mute events based on too low BWE, not network up/down.
int num_pause_events_ RTC_GUARDED_BY(&sequenced_checker_);
int64_t last_bwe_log_time_ RTC_GUARDED_BY(&sequenced_checker_);
BitrateAllocationLimits current_limits_ RTC_GUARDED_BY(&sequenced_checker_);
const uint8_t transmission_max_bitrate_multiplier_;
};
} // namespace webrtc
#endif // CALL_BITRATE_ALLOCATOR_H_