mediasoup 3.27.1 → 3.28.0

package/worker/include/RTC/BWE/IntervalBudget.hpp

@@ -0,0 +1,81 @@
+#ifndef MS_RTC_BWE_INTERVAL_BUDGET_HPP
+#define MS_RTC_BWE_INTERVAL_BUDGET_HPP
+
+#include "common.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Tracks how much of a bitrate is being used over a sliding span of time.
+		 *
+		 * The budget is a number of bytes that refills at a given bitrate and is
+		 * spent as bytes are sent, bounded in both directions by what that bitrate
+		 * delivers over a fixed window. Its level relative to that bound is the
+		 * answer to whether the sender is keeping up with the bitrate it was given:
+		 * a full budget means nothing has been sent for a while, and an empty one
+		 * means the bitrate is being used whole.
+		 *
+		 * The bound in the negative direction is what keeps a long burst from
+		 * building a debt that would take an unbounded time to pay back.
+		 */
+		class IntervalBudget
+		{
+		public:
+			explicit IntervalBudget(int64_t initialTargetBitrate);
+
+			/**
+			 * @param canBuildUpUnderuse - Whether what an interval leaves unspent is
+			 *   available to the next one. When false, an interval that spent nothing
+			 *   leaves the budget at just what that one interval refills, instead of
+			 *   adding to what was already there.
+			 */
+			IntervalBudget(int64_t initialTargetBitrate, bool canBuildUpUnderuse);
+
+			/**
+			 * Set the bitrate the budget refills at (bps).
+			 */
+			void SetTargetBitrate(int64_t targetBitrate);
+
+			int64_t GetTargetBitrate() const
+			{
+				return this->targetBitrate;
+			}
+
+			/**
+			 * Refill the budget with what the target bitrate delivers over the given
+			 * span of time.
+			 */
+			void IncreaseBudget(int64_t deltaTimeUs);
+
+			/**
+			 * Spend the given number of bytes.
+			 */
+			void UseBudget(int64_t bytes);
+
+			/**
+			 * Bytes still available, which is zero while the budget is in debt.
+			 */
+			int64_t GetBytesRemaining() const;
+
+			/**
+			 * Level of the budget as a fraction of what the window holds, from -1
+			 * when the debt is at its bound to 1 when the budget is full.
+			 */
+			double GetBudgetRatio() const;
+
+		private:
+			// Passed by argument.
+			const bool canBuildUpUnderuse;
+			// Others.
+			int64_t targetBitrate{ 0 };
+			// Bytes the target bitrate delivers over the window, which is what bounds
+			// the budget in both directions.
+			int64_t maxBytesInBudget{ 0 };
+			int64_t bytesRemaining{ 0 };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

package/worker/include/RTC/BWE/LossBasedController.hpp

@@ -40,42 +40,75 @@ namespace RTC
 		class LossBasedController
 		{
 		public:
+			/**
+			 * @remarks
+			 * - Every constraint documented below is checked by the constructor and
+			 *   aborts when it doesn't hold. These options are set from C++ alone,
+			 *   never from the network nor from the API, so breaking one of them is a
+			 *   programming error.
+			 */
 			struct LossBasedControllerOptions
 			{
 				/**
 				 * Factors applied to the current estimate to build the candidates that
 				 * are tried on every update.
+				 *
+				 * @remarks
+				 * - Every factor must be positive.
+				 * - At least one candidate other than the current estimate has to be
+				 *   reachable, so unless `appendAcknowledgedRateCandidate` or
+				 *   `appendDelayBasedEstimateCandidate` is set, one of these factors
+				 *   must differ from 1.
 				 */
 				std::vector<double> candidateFactors{ 1.02, 1.0, 0.95 };
 				/**
 				 * How much the estimate may grow over the acknowledged bitrate while
 				 * the link is loss limited.
+				 *
+				 * @remarks
+				 * - It must be greater than 1, since it's a bound above that bitrate.
 				 */
 				double bitrateRampupUpperBoundFactor{ 1.5 };
 				/**
 				 * The same while the estimate is being held, which is more conservative
 				 * because holding means that a higher bitrate already caused loss.
+				 *
+				 * @remarks
+				 * - It must be greater than 1, for the same reason.
 				 */
 				double bitrateRampupUpperBoundFactorInHold{ 1.2 };
 				/**
 				 * How far below the held bitrate the acknowledged one has to be for the
 				 * factor above to be the one applied.
+				 *
+				 * @remarks
+				 * - It must not be negative.
 				 */
 				double bitrateRampupHoldThreshold{ 1.3 };
 				/**
 				 * How much of the acknowledged bitrate the estimate may grow by on top
 				 * of its usual bound, the longer the more time has passed since it was
 				 * last reduced. Zero disables that acceleration.
+				 *
+				 * @remarks
+				 * - It must not be negative.
 				 */
 				double rampupAccelerationMaxFactor{ 0.0 };
 				/**
 				 * Time since the last reduction at which that acceleration is at its
 				 * fullest.
+				 *
+				 * @remarks
+				 * - It must be positive, since it's what the elapsed time is measured
+				 *   against.
 				 */
 				int64_t rampupAccelerationMaxoutTimeUs{ 60 * 1000 * 1000 };
 				/**
 				 * Weight given to a higher bitrate when choosing among candidates, so
 				 * that observations which cannot tell them apart don't settle low.
+				 *
+				 * @remarks
+				 * - It must not be negative.
 				 */
 				double higherBitrateBiasFactor{ 0.0002 };
 				/**
@@ -86,46 +119,78 @@ namespace RTC
 				/**
 				 * Observed loss at which the bias above is gone, since at that much loss
 				 * preferring a higher bitrate is not defensible anymore.
+				 *
+				 * @remarks
+				 * - Being a loss rate, it must be in [0, 1).
 				 */
 				double lossThresholdOfHighBitratePreference{ 0.2 };
 				/**
 				 * How abruptly that bias fades as the observed loss approaches the
 				 * threshold above.
+				 *
+				 * @remarks
+				 * - It must be in (0, 1]. Zero is excluded because it divides.
 				 */
 				double bitratePreferenceSmoothingFactor{ 0.002 };
 				/**
 				 * Lowest inherent loss that may be estimated for a link.
+				 *
+				 * @remarks
+				 * - Being a loss rate, it must be in [0, 1).
 				 */
 				double inherentLossLowerBound{ 1.0e-3 };
 				/**
 				 * Inherent loss that may be estimated at an unbounded bitrate, which
 				 * grows as the bitrate gets lower by the balance below.
+				 *
+				 * @remarks
+				 * - It must be below 1 and never below `inherentLossLowerBound`, since
+				 *   the two of them are the ends of the same range.
 				 */
 				double inherentLossUpperBoundOffset{ 0.05 };
 				/**
 				 * Bitrate at which the inherent loss upper bound grows by one, so that a
 				 * low bitrate is allowed to be explained by a lossy link.
+				 *
+				 * @remarks
+				 * - It must be positive, since it divides.
 				 */
 				int64_t inherentLossUpperBoundBitrateBalance{ 100000 };
 				/**
 				 * Inherent loss assumed before anything has been observed.
+				 *
+				 * @remarks
+				 * - Being a loss rate, it must be in [0, 1).
 				 */
 				double initialInherentLossEstimate{ 0.01 };
 				/**
 				 * Steps of Newton's method applied to each candidate.
+				 *
+				 * @remarks
+				 * - It must be positive, or no candidate would ever be refined.
 				 */
 				int64_t newtonIterations{ 1 };
 				/**
 				 * Fraction of the step that each of those iterations takes.
+				 *
+				 * @remarks
+				 * - It must be positive, or each iteration would stand still.
 				 */
 				double newtonStepSize{ 0.75 };
 				/**
 				 * Whether the acknowledged bitrate is tried as a candidate of its own.
+				 *
+				 * @remarks
+				 * - See the constraint on `candidateFactors` about there always being a
+				 *   candidate to choose from.
 				 */
 				bool appendAcknowledgedRateCandidate{ true };
 				/**
 				 * Whether the delay based estimate is tried as a candidate of its own
 				 * while it's above the current one.
+				 *
+				 * @remarks
+				 * - The same constraint as `appendAcknowledgedRateCandidate`.
 				 */
 				bool appendDelayBasedEstimateCandidate{ true };
 				/**
@@ -136,14 +201,25 @@ namespace RTC
 				bool appendUpperBoundCandidateInAlr{ false };
 				/**
 				 * Shortest span of send times that an observation may cover.
+				 *
+				 * @remarks
+				 * - It must be positive, or every packet would close an observation.
 				 */
 				int64_t observationDurationLowerBoundUs{ 250 * 1000 };
 				/**
 				 * Observations kept, which is how far back the estimate looks.
+				 *
+				 * @remarks
+				 * - It must be at least 2. It's also what every observation is indexed
+				 *   modulo, so an empty window would divide by zero.
 				 */
 				int64_t observationWindowSize{ 15 };
 				/**
 				 * Observations needed before this controller may be used at all.
+				 *
+				 * @remarks
+				 * - It must be positive, or the controller would take the estimate over
+				 *   having observed nothing.
 				 */
 				int64_t minNumObservations{ 3 };
 				/**
@@ -151,6 +227,7 @@ namespace RTC
 				 * of the previous observation.
 				 *
 				 * @remarks
+				 * - It must be in [0, 1).
 				 * - Zero means no smoothing at all, which is what libwebrtc does. A
 				 *   sender of a couple of streams has a sending rate that only changes
 				 *   when it decides so, while ours is the sum of many streams whose
@@ -160,38 +237,66 @@ namespace RTC
 				/**
 				 * How much weight each observation loses per observation of age when
 				 * looking for the most likely pair of values.
+				 *
+				 * @remarks
+				 * - It must be in (0, 1]. One means that age doesn't weigh at all, and
+				 *   zero is excluded because it would leave every observation but the
+				 *   latest one weightless.
 				 */
 				double temporalWeightFactor{ 0.9 };
 				/**
 				 * The same, for the average observed loss that bounds the estimate right
 				 * away.
+				 *
+				 * @remarks
+				 * - It must be in (0, 1], for the same reason.
 				 */
 				double immediateUpperBoundTemporalWeightFactor{ 0.9 };
 				/**
 				 * Observed loss under which no immediate upper bound is applied.
+				 *
+				 * @remarks
+				 * - Being a loss rate, it must be in [0, 1).
 				 */
 				double immediateUpperBoundLossOffset{ 0.05 };
 				/**
 				 * Bitrate the immediate upper bound allows per unit of observed loss
 				 * over the offset above.
+				 *
+				 * @remarks
+				 * - It must be positive, since it multiplies a bound that would
+				 *   otherwise collapse to nothing.
 				 */
 				int64_t immediateUpperBoundBitrateBalance{ 100000 };
 				/**
 				 * How much of the acknowledged bitrate the estimate may never go below.
+				 *
+				 * @remarks
+				 * - It must not be negative.
 				 */
 				double lowerBoundByAckedRateFactor{ 1.0 };
 				/**
 				 * Fraction of the acknowledged bitrate taken as a candidate when backing
 				 * off.
+				 *
+				 * @remarks
+				 * - It must not be greater than 1, since backing off to more than what
+				 *   is acknowledged is not backing off.
 				 */
 				double bitrateBackoffLowerBoundFactor{ 1.0 };
 				/**
 				 * How much the estimate may grow within the window that follows a
 				 * decrease.
+				 *
+				 * @remarks
+				 * - It must be positive.
 				 */
 				double maxIncreaseFactor{ 1.3 };
 				/**
 				 * How long that window lasts.
+				 *
+				 * @remarks
+				 * - It must be positive.
 				 */
 				int64_t delayedIncreaseWindowUs{ 300 * 1000 };
 				/**

package/worker/include/RTC/BWE/OveruseDetector.hpp

@@ -0,0 +1,71 @@
+#ifndef MS_RTC_BWE_OVERUSE_DETECTOR_HPP
+#define MS_RTC_BWE_OVERUSE_DETECTOR_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Decides whether the network is congested from how much the delay between
+		 * groups of packets is growing.
+		 *
+		 * The trend it is given is compared against a threshold that adapts itself
+		 * to the noise observed, and congestion is only declared once the condition
+		 * has persisted, which is what keeps an isolated jitter spike from bringing
+		 * the estimate down.
+		 *
+		 * @remarks
+		 * - This is what the receiving side uses, paired with `OveruseEstimator`.
+		 *   The sending side has `TrendlineEstimator`, which does both jobs at once
+		 *   and shares this very threshold machinery.
+		 */
+		class OveruseDetector
+		{
+		public:
+			OveruseDetector() = default;
+
+			~OveruseDetector() = default;
+
+			OveruseDetector(const OveruseDetector&)            = delete;
+			OveruseDetector& operator=(const OveruseDetector&) = delete;
+
+			/**
+			 * Feed what the estimator makes of the latest pair of groups.
+			 *
+			 * @param offsetMs - Part of the delay between both groups that the traffic
+			 *   itself doesn't explain.
+			 * @param sendDeltaMs - Time between the send times of both groups, which
+			 *   is how long this sample is worth.
+			 * @param numOfDeltas - Number of samples that offset is based on.
+			 * @param nowUs - Current time.
+			 *
+			 * @returns What the network is taken to be doing after this sample.
+			 */
+			Types::BandwidthUsage Detect(
+			  double offsetMs, double sendDeltaMs, int64_t numOfDeltas, int64_t nowUs);
+
+			Types::BandwidthUsage GetState() const
+			{
+				return this->state;
+			}
+
+		private:
+			void UpdateThreshold(double modifiedOffsetMs, int64_t nowUs);
+
+		private:
+			double threshold{ 12.5 };
+			std::optional<int64_t> lastThresholdUpdateAtUs;
+			double prevOffsetMs{ 0.0 };
+			// How long the trend has been above the threshold, or no value while it
+			// isn't.
+			std::optional<double> timeOverUsingMs;
+			int64_t overuseCounter{ 0 };
+			Types::BandwidthUsage state{ Types::BandwidthUsage::NORMAL };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

package/worker/include/RTC/BWE/OveruseEstimator.hpp

@@ -0,0 +1,115 @@
+#ifndef MS_RTC_BWE_OVERUSE_ESTIMATOR_HPP
+#define MS_RTC_BWE_OVERUSE_ESTIMATOR_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include <deque>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Estimates how much the delay between groups of packets is growing, and how
+		 * noisy that measure is.
+		 *
+		 * It fits a two variable model to what each pair of groups showed: how much
+		 * of the extra delay is explained by the group being bigger, and how much is
+		 * left over once that is taken out. The second one is the interesting part,
+		 * since a delay that grows without the traffic growing is a queue filling up
+		 * somewhere.
+		 *
+		 * Both are tracked with a Kalman filter, which is what lets the estimate
+		 * follow the network while telling apart a real trend from the jitter that
+		 * every link has. The noise it measures along the way is what the detector
+		 * compares the trend against.
+		 *
+		 * @remarks
+		 * - This is what the receiving side uses, where the only thing known about
+		 *   when a packet was sent is the timestamp it carries. The sending side has
+		 *   the real instants, so it uses `TrendlineEstimator` instead, which fits a
+		 *   line rather than filtering.
+		 */
+		class OveruseEstimator
+		{
+		public:
+			OveruseEstimator() = default;
+
+			~OveruseEstimator() = default;
+
+			OveruseEstimator(const OveruseEstimator&)            = delete;
+			OveruseEstimator& operator=(const OveruseEstimator&) = delete;
+
+			/**
+			 * Feed the deltas between two consecutive groups of packets.
+			 *
+			 * @param arrivalDeltaMs - Time elapsed between the arrival of both groups.
+			 * @param sendDeltaMs - Time elapsed between the send times of both groups.
+			 * @param sizeDelta - Difference of size between both groups (bytes).
+			 * @param currentHypothesis - What the detector makes of the network right
+			 *   now, which decides whether this sample is used to measure the noise
+			 *   and how much the filter is allowed to move.
+			 */
+			void Update(
+			  double arrivalDeltaMs,
+			  double sendDeltaMs,
+			  int64_t sizeDelta,
+			  Types::BandwidthUsage currentHypothesis);
+
+			/**
+			 * Estimated variance of the noise (ms^2).
+			 */
+			double GetVarNoiseMs2() const
+			{
+				return this->varNoiseMs2;
+			}
+
+			/**
+			 * Estimated part of the delay between groups that the traffic itself
+			 * doesn't explain (ms).
+			 */
+			double GetOffsetMs() const
+			{
+				return this->offsetMs;
+			}
+
+			/**
+			 * Number of samples the current estimate is based on.
+			 */
+			int64_t GetNumOfDeltas() const
+			{
+				return this->numOfDeltas;
+			}
+
+		private:
+			/**
+			 * Shortest send delta of the recent history, which is what the noise
+			 * estimate is scaled by so that it doesn't depend on how often packets
+			 * come.
+			 */
+			double UpdateMinFramePeriod(double sendDeltaMs);
+
+			void UpdateNoiseEstimate(double residual, double minFramePeriodMs, bool stableState);
+
+		private:
+			int64_t numOfDeltas{ 0 };
+			// How much of the extra delay a bigger group explains (ms per byte).
+			double slopeMsPerByte{ 8.0 / 512.0 };
+			// What is left of it once that is taken out (ms).
+			double offsetMs{ 0.0 };
+			double prevOffsetMs{ 0.0 };
+			// Covariance of the two values above, and how much they are allowed to
+			// move on their own between samples.
+			double e[2][2]{
+				{ 100.0, 0.0  },
+        { 0.0,   1e-1 }
+			};
+			double processNoise[2]{ 1e-13, 1e-3 };
+			double avgNoiseMs{ 0.0 };
+			double varNoiseMs2{ 50.0 };
+			std::deque<double> sendDeltaHistMs;
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

package/worker/include/RTC/BWE/ProbeBitrateEstimator.hpp

@@ -0,0 +1,84 @@
+#ifndef MS_RTC_BWE_PROBE_BITRATE_ESTIMATOR_HPP
+#define MS_RTC_BWE_PROBE_BITRATE_ESTIMATOR_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include <ankerl/unordered_dense.h>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Measures what a probe actually achieved.
+		 *
+		 * A probe is a burst of packets sent on purpose above the current estimate,
+		 * and the point of it is to learn the capacity of the link directly instead
+		 * of inferring it from the delay. This class gathers the feedback of the
+		 * packets of each burst and, once enough of the burst has come back, says at
+		 * what bitrate it was delivered.
+		 *
+		 * The answer is the lower of the rate it was sent at and the rate it
+		 * arrived at, because a burst that arrives faster than it was sent measures
+		 * the sender and not the link. And when it arrives clearly slower than it
+		 * was sent, that means the burst found the real capacity, so the answer is
+		 * taken slightly below what arrived in order not to overuse it right away.
+		 *
+		 * A burst that too little of came back, that was sent or received over too
+		 * long a span, or that arrived far faster than it was sent, is discarded
+		 * rather than believed.
+		 */
+		class ProbeBitrateEstimator
+		{
+		private:
+			/**
+			 * What has been gathered so far about a burst.
+			 */
+			struct AggregatedCluster
+			{
+				int64_t numProbes{ 0 };
+				std::optional<int64_t> firstSendTimeUs;
+				std::optional<int64_t> lastSendTimeUs;
+				std::optional<int64_t> firstReceiveTimeUs;
+				std::optional<int64_t> lastReceiveTimeUs;
+				// Size of the packet sent last, which the span of send times doesn't
+				// cover.
+				int64_t sizeLastSend{ 0 };
+				// Size of the packet received first, which the span of receive times
+				// doesn't cover.
+				int64_t sizeFirstReceive{ 0 };
+				int64_t sizeTotal{ 0 };
+			};
+
+		public:
+			/**
+			 * Feed the feedback of a packet that belongs to a probe.
+			 *
+			 * @returns The bitrate the probe achieved (bps), or no value while its
+			 * burst cannot be trusted yet or at all.
+			 */
+			std::optional<int64_t> HandleProbeAndEstimateBitrate(const Types::PacketResult& packetResult);
+
+			/**
+			 * Take the latest measured bitrate (bps), leaving none behind, so that a
+			 * probe is never acted upon twice.
+			 */
+			std::optional<int64_t> FetchAndResetLastEstimatedBitrate();
+
+		private:
+			/**
+			 * Forget the bursts whose last packet arrived long enough ago that they
+			 * cannot receive anything else.
+			 */
+			void EraseOldClusters(int64_t nowUs);
+
+		private:
+			// Bursts being gathered, by their id. Nothing looks at them in any
+			// particular order.
+			ankerl::unordered_dense::map<int64_t, AggregatedCluster> clusters;
+			std::optional<int64_t> estimatedBitrate;
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif