mediasoup 3.26.0 → 3.27.1

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

@@ -0,0 +1,94 @@
+#ifndef MS_RTC_BWE_ROBUST_THROUGHPUT_ESTIMATOR_HPP
+#define MS_RTC_BWE_ROBUST_THROUGHPUT_ESTIMATOR_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/AcknowledgedBitrateEstimatorInterface.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include <deque>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Measures the acknowledged bitrate over a sliding window of the packets the
+		 * receiver reported.
+		 *
+		 * The estimate is the smaller of the send rate and the receive rate observed
+		 * over that window, so that it never claims more than what was actually put
+		 * on the wire. The largest gap between arrivals is replaced by the second
+		 * largest one before dividing, which is what keeps a short pause followed by
+		 * a burst of delayed packets from collapsing the estimate.
+		 */
+		class RobustThroughputEstimator : public AcknowledgedBitrateEstimatorInterface
+		{
+		public:
+			struct RobustThroughputEstimatorOptions
+			{
+				/**
+				 * Smallest number of packets the window holds.
+				 */
+				size_t windowPackets{ 20 };
+				/**
+				 * Largest number of packets the window holds, so that a high bitrate
+				 * doesn't make it grow without bound.
+				 */
+				size_t maxWindowPackets{ 500 };
+				/**
+				 * Smallest duration the window covers, so that a low bitrate still gets
+				 * enough packets to measure.
+				 */
+				int64_t minWindowDurationUs{ 1000 * 1000 };
+				/**
+				 * Largest duration the window covers, so that very old packets don't
+				 * weigh on the estimate after sending was paused.
+				 */
+				int64_t maxWindowDurationUs{ 5 * 1000 * 1000 };
+				/**
+				 * Number of packets the window needs before it produces an estimate.
+				 */
+				size_t requiredPackets{ 10 };
+				/**
+				 * Weight given to the data that was sent but is not covered by any
+				 * feedback.
+				 *
+				 * @remarks
+				 * - Set it to 0 when audio is not included in the allocation, and to 1
+				 *   when it is included in the allocation but not in the estimation.
+				 *   Its value is irrelevant once every packet is tracked.
+				 */
+				double unackedWeight{ 1.0 };
+			};
+
+		public:
+			RobustThroughputEstimator();
+
+			explicit RobustThroughputEstimator(RobustThroughputEstimatorOptions options);
+
+			void IncomingPacketFeedbackVector(const std::vector<Types::PacketResult>& packetResults) override;
+
+			std::optional<int64_t> GetBitrate() const override;
+
+			void SetAlr(bool /*inAlr*/) override
+			{
+			}
+
+			void SetAlrEndedTimeUs(int64_t /*alrEndedTimeUs*/) override
+			{
+			}
+
+		private:
+			/**
+			 * Whether the oldest packet of the window no longer belongs to it.
+			 */
+			bool IsFirstPacketOutsideWindow() const;
+
+		private:
+			const RobustThroughputEstimatorOptions options;
+			std::deque<Types::PacketResult> window;
+			std::optional<int64_t> latestDiscardedSendTimeUs;
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

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

@@ -0,0 +1,137 @@
+#ifndef MS_RTC_BWE_SEND_PACKET_HISTORY_HPP
+#define MS_RTC_BWE_SEND_PACKET_HISTORY_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include <map>
+#include <tuple>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Holds every packet that was sent until a feedback reports on it.
+		 *
+		 * Packets are indexed by a sequence number of its own, handed out by this
+		 * history, so that nothing about how a feedback identifies a packet leaks
+		 * in here. Each packet also keeps its SSRC and RTP sequence number, which
+		 * is what allows a feedback that identifies packets that way to be resolved
+		 * against this very same history.
+		 *
+		 * It also tracks how many bytes are in flight, which are those that were
+		 * sent and no feedback has reported on yet.
+		 *
+		 * @see https://datatracker.ietf.org/doc/html/draft-holmer-rmcat-transport-wide-cc-extensions
+		 * @see https://datatracker.ietf.org/doc/html/rfc8888
+		 */
+		class SendPacketHistory
+		{
+		public:
+			struct SendPacketHistoryOptions
+			{
+				/**
+				 * Time a packet is kept for, beyond which a feedback reporting on it
+				 * arrives too late to be of any use.
+				 */
+				int64_t windowDurationUs{ 60 * 1000 * 1000 };
+			};
+
+		private:
+			struct SentPacketEntry
+			{
+				Types::SentPacket sentPacket;
+				uint32_t ssrc{ 0 };
+				uint16_t seq{ 0 };
+			};
+
+			struct SsrcAndSeq
+			{
+				bool operator<(const SsrcAndSeq& other) const
+				{
+					return std::tie(this->ssrc, this->seq) < std::tie(other.ssrc, other.seq);
+				}
+
+				uint32_t ssrc{ 0 };
+				uint16_t seq{ 0 };
+			};
+
+		public:
+			SendPacketHistory();
+
+			explicit SendPacketHistory(SendPacketHistoryOptions options);
+
+			/**
+			 * Take note of a packet that has just been sent.
+			 *
+			 * @param size - Size of the packet including overhead up to the IP layer
+			 *   (bytes).
+			 * @param audio - Whether it's an audio packet. False for video, padding
+			 *   and RTX.
+			 * @returns The sequence number given to the packet, which is what a
+			 *   feedback has to be resolved into.
+			 */
+			int64_t AddPacket(uint32_t ssrc, uint16_t seq, size_t size, bool audio, int64_t sentAtUs);
+
+			/**
+			 * Resolve what a feedback reported about a single packet.
+			 *
+			 * @param received - Whether the feedback reported the packet as received.
+			 * @returns The packet as it was sent, or no value if this history doesn't
+			 *   hold it anymore.
+			 *
+			 * @remarks
+			 * - Every packet up to the given one stops counting as in flight, since
+			 *   the feedback settles whether it arrived or not.
+			 * - A packet reported as received is dropped, while one reported as lost
+			 *   is kept, since a later feedback may still report it as received.
+			 */
+			std::optional<Types::SentPacket> RetrievePacket(int64_t sequenceNumber, bool received);
+
+			/**
+			 * Same, for a feedback that identifies the packet by its SSRC and RTP
+			 * sequence number rather than by the sequence number given to it.
+			 */
+			std::optional<Types::SentPacket> RetrievePacket(uint32_t ssrc, uint16_t seq, bool received);
+
+			/**
+			 * Sequence number this history gave to the latest packet added, or no
+			 * value if no packet was ever added.
+			 *
+			 * @remarks
+			 * - It's the sequence number of this history, not the RTP one, so it
+			 *   never wraps around. It's also the highest a feedback carrying only
+			 *   the lowest bits of it can possibly stand for.
+			 */
+			std::optional<int64_t> GetLastSequenceNumber() const;
+
+			/**
+			 * Bytes that were sent and no feedback has reported on yet.
+			 */
+			size_t GetOutstandingBytes() const
+			{
+				return this->outstandingBytes;
+			}
+
+		private:
+			void RemoveOutstandingBytes(const SentPacketEntry& entry);
+
+			/**
+			 * Drop the mapping of a packet, unless the same SSRC and RTP sequence
+			 * number were sent again afterwards and hence took it over.
+			 */
+			void RemoveSsrcAndSeq(const SentPacketEntry& entry);
+
+		private:
+			const SendPacketHistoryOptions options;
+			std::map<int64_t, SentPacketEntry> history;
+			std::map<SsrcAndSeq, int64_t> ssrcAndSeqToSequenceNumber;
+			int64_t nextSequenceNumber{ 0 };
+			// Sequence numbers are never negative, so this sits below all of them.
+			int64_t lastAckSequenceNumber{ -1 };
+			size_t outstandingBytes{ 0 };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

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

@@ -0,0 +1,306 @@
+#ifndef MS_RTC_BWE_TARGET_RATE_CONTROLLER_HPP
+#define MS_RTC_BWE_TARGET_RATE_CONTROLLER_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include "RTC/BWE/LossBasedController.hpp"
+#include <deque>
+#include <vector>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Holds the target bitrate and every bound that applies to it.
+		 *
+		 * The delay based path, the receiver of the media and the application each
+		 * produce a limit rather than a bitrate, so something has to hold the value
+		 * they bound and decide how it moves within them. That is this class, and it
+		 * also owns the two inputs that move the target down on their own: a round
+		 * trip time long enough to mean that the queues of the network are full, and
+		 * the loss the receiver reports.
+		 *
+		 * How loss moves the target depends on how much is known about it. Until the
+		 * loss controller has seen enough feedback to tell congestion from the loss a
+		 * link has by itself, this class applies rules of its own on the fraction of
+		 * packets reported as lost: increase while it stays under 2%, leave the target
+		 * alone up to 10%, and decrease it above that. They are coarse on purpose, and
+		 * their weakness is precisely what they cannot tell apart, so on a link with
+		 * steady loss above 2% they hold the target still and above 10% they drive it
+		 * to the minimum. As soon as the loss controller is ready, its estimate
+		 * replaces them.
+		 *
+		 * @remarks
+		 * - This class is a port of the SendSideBandwidthEstimation class in
+		 *   libwebrtc (renamed to a better name).
+		 */
+		class TargetRateController
+		{
+		public:
+			struct TargetRateControllerOptions
+			{
+				/**
+				 * Reported loss under which the bitrate is increased.
+				 */
+				double lowLossThreshold{ 0.02 };
+				/**
+				 * Reported loss over which the bitrate is decreased.
+				 */
+				double highLossThreshold{ 0.1 };
+				/**
+				 * Bitrate under which loss is ignored altogether, since at a low enough
+				 * bitrate loss is unlikely to be caused by the traffic itself.
+				 */
+				int64_t bitrateThreshold{ 0 };
+				/**
+				 * Whether the bound asked for by the receiver takes part in how the
+				 * target moves, rather than only capping the value this controller
+				 * hands out.
+				 */
+				bool disableReceiverLimitCapsOnly{ false };
+				/**
+				 * Round trip time over which the bitrate is dropped regardless of loss.
+				 * A round trip time this long means the queues of the network are full.
+				 */
+				int64_t maxRttUs{ 3 * 1000 * 1000 };
+				/**
+				 * Fraction of the target the bitrate is dropped to on each of those
+				 * drops.
+				 */
+				double rttBackoffDropFraction{ 0.8 };
+				/**
+				 * How often the bitrate may be dropped due to the round trip time.
+				 */
+				int64_t rttBackoffDropIntervalUs{ 1000 * 1000 };
+				/**
+				 * Bitrate the round trip time backoff never drops below.
+				 */
+				int64_t rttBackoffBitrateFloor{ 5000 };
+			};
+
+		private:
+			/**
+			 * Drops the bitrate when the round trip time stays long enough to mean
+			 * that the queues of the network are full, which is a congestion signal
+			 * that loss and delay may both miss.
+			 */
+			struct RttBackoff
+			{
+				/**
+				 * Round trip time corrected for the sender being idle. Without the
+				 * correction a sender that stops transmitting would keep reporting the
+				 * last measured value forever.
+				 */
+				int64_t GetCorrectedRttUs() const
+				{
+					int64_t timeoutCorrectionUs{ 0 };
+
+					// While either instant is missing there is nothing to correct: no
+					// feedback has arrived, or nothing that gets feedback has been sent.
+					if (this->lastPacketSentAtUs.has_value() && this->lastPropagationRttAtUs.has_value())
+					{
+						timeoutCorrectionUs = std::max<int64_t>(
+						  this->lastPacketSentAtUs.value() - this->lastPropagationRttAtUs.value(), 0);
+					}
+
+					return timeoutCorrectionUs + this->lastPropagationRttUs;
+				}
+
+				std::optional<int64_t> lastPropagationRttAtUs;
+				std::optional<int64_t> lastPacketSentAtUs;
+				int64_t lastPropagationRttUs{ 0 };
+			};
+
+		public:
+			TargetRateController();
+
+			explicit TargetRateController(TargetRateControllerOptions options);
+
+			/**
+			 * Bitrate this controller may produce, already within every bound.
+			 */
+			int64_t GetTargetBitrate() const;
+
+			/**
+			 * Latest fraction of lost packets reported by the receiver, in 1/256 units.
+			 */
+			uint8_t GetFractionLost() const
+			{
+				return this->lastFractionLost;
+			}
+
+			int64_t GetRttUs() const
+			{
+				return this->lastRttUs;
+			}
+
+			/**
+			 * Whether the round trip time is long enough to be taken as congestion on
+			 * its own.
+			 */
+			bool IsRttAboveLimit() const
+			{
+				return this->rttBackoff.GetCorrectedRttUs() > this->options.maxRttUs;
+			}
+
+			/**
+			 * Forget everything learnt about the network, which is what a transport
+			 * that is not going through the same path anymore calls for.
+			 *
+			 * @remarks
+			 * - The bounds set by the application are dropped too, so they have to be
+			 *   set again afterwards.
+			 */
+			void OnRouteChange();
+
+			/**
+			 * Bounds set by the application.
+			 *
+			 * @remarks
+			 * - A max bitrate of zero means no limit.
+			 */
+			void SetBitrateLimits(int64_t minBitrate, int64_t maxBitrate);
+
+			/**
+			 * Place the target at the given bitrate, dropping the bound that could
+			 * hold it back and the history that limits how fast it grows.
+			 */
+			void SetSendBitrate(int64_t bitrate);
+
+			/**
+			 * Upper bound produced by the delay based path.
+			 */
+			void SetDelayBasedEstimate(int64_t bitrate);
+
+			/**
+			 * Upper bound asked for by the receiver of the media, which reaches us as
+			 * a REMB message.
+			 *
+			 * @remarks
+			 * - A bitrate of zero means no limit.
+			 */
+			void SetReceiverEstimate(int64_t bitrate);
+
+			/**
+			 * Feed a loss report of the receiver.
+			 *
+			 * @remarks
+			 * - Reports are accumulated until they cover enough packets, so most calls
+			 *   change nothing.
+			 */
+			void UpdatePacketsLost(int64_t lostPackets, int64_t totalPackets, int64_t nowUs);
+
+			void UpdateRtt(int64_t rttUs);
+
+			/**
+			 * Feed the round trip time the round trip time backoff watches, which is
+			 * the one measured by the transport feedback rather than by RTCP.
+			 */
+			void UpdatePropagationRtt(int64_t propagationRttUs, int64_t nowUs);
+
+			/**
+			 * Tell that a packet that will be reported back has just been sent.
+			 */
+			void OnPacketSent(int64_t sentAtUs);
+
+			/**
+			 * Reconsider the target. Called after every loss report and periodically,
+			 * since the increase depends on how much time has elapsed.
+			 */
+			void Update(int64_t nowUs);
+
+			/**
+			 * Bitrate the network is known to be delivering.
+			 */
+			void SetAcknowledgedBitrate(int64_t acknowledgedBitrate);
+
+			/**
+			 * Feed the results of a feedback message to the loss controller, which is
+			 * the only thing in here that looks at packets one by one.
+			 *
+			 * @param inAlr - Whether the sender is not sending enough to fill the link.
+			 */
+			void UpdateLossBasedController(
+			  const std::vector<Types::PacketResult>& packetResults, bool inAlr, int64_t nowUs);
+
+			/**
+			 * What the loss controller is doing with the target, which tells whether
+			 * probing makes sense.
+			 */
+			LossBasedController::State GetLossBasedState() const
+			{
+				return this->lossBasedState;
+			}
+
+		private:
+			/**
+			 * Whether the target is still allowed to just follow the bounds because
+			 * not enough is known about the network yet.
+			 */
+			bool IsInStartPhase(int64_t nowUs) const;
+
+			/**
+			 * Lowest bitrate the target has had during the last second, which is what
+			 * the increase grows from.
+			 */
+			void UpdateMinBitrateHistory(int64_t nowUs);
+
+			/**
+			 * Upper bound of every kind that applies to the target.
+			 */
+			int64_t GetUpperLimit() const;
+
+			/**
+			 * Set the target to the given bitrate, keeping it within its bounds.
+			 */
+			void SetTargetBitrate(int64_t bitrate);
+
+			/**
+			 * Reapply the bounds to the current target, which is needed when one of
+			 * them changes.
+			 */
+			void ApplyTargetLimits();
+
+		private:
+			// Passed by argument.
+			const TargetRateControllerOptions options;
+			// Others.
+			// Tells congestion from the loss the link has by itself, and takes over
+			// the target as soon as it has enough observations.
+			LossBasedController lossBasedController;
+			LossBasedController::State lossBasedState{ LossBasedController::State::DELAY_BASED_ESTIMATE };
+			struct RttBackoff rttBackoff;
+			// Lowest target of the last second, as a sliding window minimum of
+			// (instant in us, bitrate in bps) pairs.
+			std::deque<std::pair<int64_t, int64_t>> minBitrateHistory;
+			// Loss reports too small to tell anything on their own, accumulated until
+			// they cover enough packets.
+			int64_t lostPacketsSinceLastLossUpdate{ 0 };
+			int64_t expectedPacketsSinceLastLossUpdate{ 0 };
+			int64_t currentTarget{ 0 };
+			int64_t minBitrateConfigured{ 0 };
+			int64_t maxBitrateConfigured{ 0 };
+			// Instant of the first loss report ever received, which is when the start
+			// phase begins.
+			std::optional<int64_t> firstLossReportAtUs;
+			// Instant of the latest loss report that covered enough packets to tell
+			// something.
+			std::optional<int64_t> lastLossReportAtUs;
+			// Instant at which the target was last decreased, by the loss rules or by
+			// the round trip time backoff.
+			std::optional<int64_t> lastDecreaseAtUs;
+			// Whether the target has already been decreased for the loss currently
+			// reported, so that a same report doesn't decrease it twice.
+			bool hasDecreasedSinceLastFractionLoss{ false };
+			uint8_t lastFractionLost{ 0 };
+			int64_t lastRttUs{ 0 };
+			// Upper bound asked for by the receiver of the media.
+			int64_t receiverLimit{ Types::BitrateInfinite };
+			// Upper bound produced by the delay based path.
+			int64_t delayBasedLimit{ Types::BitrateInfinite };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

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

@@ -0,0 +1,143 @@
+#ifndef MS_RTC_BWE_TRENDLINE_ESTIMATOR_HPP
+#define MS_RTC_BWE_TRENDLINE_ESTIMATOR_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include <deque>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Detects network congestion from the delay between groups of packets,
+		 * before any packet is lost.
+		 *
+		 * For each pair of consecutive groups it accumulates `arrivalDelta -
+		 * sendDelta`, smooths it, and fits a least squares line over the last
+		 * `WindowSize` samples. The slope of that line approximates
+		 * `(sendRate - capacity) / capacity`, so a positive slope means that queues
+		 * are filling up somewhere in the network.
+		 *
+		 * That slope is compared against a threshold that adapts itself to the
+		 * observed noise, and overuse is only declared once the condition persists,
+		 * which is what prevents an isolated jitter spike from bringing the estimate
+		 * down.
+		 */
+		class TrendlineEstimator
+		{
+		public:
+			struct TrendlineEstimatorOptions
+			{
+				/**
+				 * Number of samples of the least squares regression window. A shorter
+				 * window reacts sooner at the cost of being noisier.
+				 *
+				 * @remarks
+				 * - It must be at least 2, since a line cannot be fitted to a single
+				 *   point.
+				 */
+				size_t windowSize{ 20 };
+				/**
+				 * Whether the samples of the window are kept sorted by arrival time.
+				 * Feedback should already give them in order, so this is a safety net
+				 * against a source that doesn't.
+				 */
+				bool enableSort{ false };
+				/**
+				 * Whether the slope is capped by the one that the least delayed packets
+				 * of both ends of the window describe, which keeps a burst of delayed
+				 * packets in the middle from being read as a growing queue.
+				 */
+				bool enableCap{ false };
+				/**
+				 * How many packets of the beginning of the window that cap looks at.
+				 */
+				size_t beginningPackets{ 7 };
+				/**
+				 * How many packets of the end of the window that cap looks at.
+				 */
+				size_t endPackets{ 7 };
+				/**
+				 * Slack added to that cap, so that a slope barely above it is not
+				 * capped.
+				 */
+				double capUncertainty{ 0.0 };
+			};
+
+		private:
+			struct PacketTiming
+			{
+				double arrivalTimeUs;
+				double smoothedDelayUs;
+				/**
+				 * Accumulated delay before it's smoothed, which is what the slope cap
+				 * looks at.
+				 */
+				double rawDelayUs;
+			};
+
+		public:
+			TrendlineEstimator();
+
+			explicit TrendlineEstimator(TrendlineEstimatorOptions options);
+
+			/**
+			 * Feed the deltas between two consecutive groups of packets.
+			 *
+			 * @param sendDeltaUs - Time elapsed between the send times of both groups.
+			 * @param arrivalDeltaUs - Time elapsed between the arrival times of both
+			 *   groups.
+			 * @param arrivalTimeUs - Arrival time of the latest group, in the remote
+			 *   clock reference.
+			 */
+			void Update(int64_t sendDeltaUs, int64_t arrivalDeltaUs, int64_t arrivalTimeUs);
+
+			/**
+			 * Current hypothesis about how the network is behaving.
+			 */
+			Types::BandwidthUsage GetState() const
+			{
+				return this->state;
+			}
+
+		private:
+			/**
+			 * Slope of the least squares line fitted to the samples window, or no
+			 * value if it cannot be computed.
+			 */
+			std::optional<double> GetLinearFitSlope() const;
+
+			/**
+			 * Highest slope that the least delayed samples of both ends of the window
+			 * describe, or no value if they are too close in time to tell.
+			 *
+			 * @remarks
+			 * - A burst of delayed packets in the middle of the window tilts the
+			 *   fitted line even though the queue never grew, and this is what keeps
+			 *   that from being read as overuse.
+			 */
+			std::optional<double> GetSlopeCap() const;
+
+			void Detect(double trend, double sendDeltaUs, int64_t arrivalTimeUs);
+
+			void UpdateThreshold(double modifiedTrend, int64_t arrivalTimeUs);
+
+		private:
+			const TrendlineEstimatorOptions options;
+			int numOfDeltas{ 0 };
+			std::optional<int64_t> firstArrivalTimeUs;
+			double accumulatedDelayUs{ 0 };
+			double smoothedDelayUs{ 0 };
+			std::deque<PacketTiming> delayHist;
+			double threshold{ 12.5 };
+			double prevTrend{ 0 };
+			std::optional<double> timeOverUsingUs;
+			int overuseCounter{ 0 };
+			std::optional<int64_t> lastThresholdUpdateAtUs;
+			Types::BandwidthUsage state{ Types::BandwidthUsage::NORMAL };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif