mediasoup 3.26.0 → 3.27.0

package/worker/src/RTC/BWE/LinkCapacityEstimator.cpp

@@ -0,0 +1,133 @@
+#define MS_CLASS "RTC::BWE::LinkCapacityEstimator"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/LinkCapacityEstimator.hpp"
+#include "Logger.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include <cmath>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Static. */
+
+		// Weight given to a sample taken when overuse was detected. It's low because
+		// such a sample only tells that the capacity was exceeded, not where it is.
+		static constexpr double OveruseAlpha{ 0.05 };
+		// Weight given to a sample measured by a probe, which is far higher since a
+		// probe measures the capacity of the link rather than inferring it.
+		static constexpr double ProbeAlpha{ 0.5 };
+		// Number of standard deviations covered by the confidence interval.
+		static constexpr double BoundDeviations{ 3.0 };
+		// Bounds of the tracked variance, which is normalized by the estimate itself.
+		// The lower one is around 14 kbps at 500 kbps and the upper one around
+		// 35 kbps at 500 kbps.
+		static constexpr double MinDeviationKbps{ 0.4 };
+		static constexpr double MaxDeviationKbps{ 2.5 };
+
+		/* Instance methods. */
+
+		void LinkCapacityEstimator::OnOveruseDetected(int64_t ackedBitrate)
+		{
+			MS_TRACE();
+
+			Update(ackedBitrate, OveruseAlpha);
+		}
+
+		void LinkCapacityEstimator::OnProbeRate(int64_t probeBitrate)
+		{
+			MS_TRACE();
+
+			Update(probeBitrate, ProbeAlpha);
+		}
+
+		std::optional<int64_t> LinkCapacityEstimator::GetEstimate() const
+		{
+			MS_TRACE();
+
+			if (!this->estimateKbps.has_value())
+			{
+				return std::nullopt;
+			}
+
+			return static_cast<int64_t>(this->estimateKbps.value() * 1000);
+		}
+
+		int64_t LinkCapacityEstimator::GetUpperBound() const
+		{
+			MS_TRACE();
+
+			if (!this->estimateKbps.has_value())
+			{
+				return Types::BitrateInfinite;
+			}
+
+			const double upperBoundKbps =
+			  this->estimateKbps.value() + (BoundDeviations * GetDeviationEstimateKbps());
+
+			return static_cast<int64_t>(upperBoundKbps * 1000);
+		}
+
+		int64_t LinkCapacityEstimator::GetLowerBound() const
+		{
+			MS_TRACE();
+
+			if (!this->estimateKbps.has_value())
+			{
+				return 0;
+			}
+
+			const double lowerBoundKbps =
+			  std::max(0.0, this->estimateKbps.value() - (BoundDeviations * GetDeviationEstimateKbps()));
+
+			return static_cast<int64_t>(lowerBoundKbps * 1000);
+		}
+
+		void LinkCapacityEstimator::Reset()
+		{
+			MS_TRACE();
+
+			// NOTE: The tracked variance is deliberately kept, since how noisy the
+			// samples are is a property of the network rather than of the estimate
+			// being dropped.
+			this->estimateKbps.reset();
+		}
+
+		void LinkCapacityEstimator::Update(int64_t bitrate, double alpha)
+		{
+			MS_TRACE();
+
+			// NOTE: Samples are taken with a resolution of 1 kbps.
+			const double sampleKbps = std::round(static_cast<double>(bitrate) / 1000.0);
+
+			if (!this->estimateKbps.has_value())
+			{
+				this->estimateKbps = sampleKbps;
+			}
+			else
+			{
+				this->estimateKbps = ((1 - alpha) * this->estimateKbps.value()) + (alpha * sampleKbps);
+			}
+
+			// Estimate the variance of the estimate, normalized by the estimate itself
+			// so that it's comparable across bitrates.
+			const double norm      = std::max(this->estimateKbps.value(), 1.0);
+			const double errorKbps = this->estimateKbps.value() - sampleKbps;
+
+			this->deviationKbps =
+			  ((1 - alpha) * this->deviationKbps) + (alpha * errorKbps * errorKbps / norm);
+			this->deviationKbps = std::clamp(this->deviationKbps, MinDeviationKbps, MaxDeviationKbps);
+		}
+
+		double LinkCapacityEstimator::GetDeviationEstimateKbps() const
+		{
+			MS_TRACE();
+
+			// The tracked variance is normalized by the estimate, so it has to be
+			// scaled back by it before taking the standard deviation.
+			// NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+			return std::sqrt(this->deviationKbps * this->estimateKbps.value());
+		}
+	} // namespace BWE
+} // namespace RTC

package/worker/src/RTC/BWE/RobustThroughputEstimator.cpp

@@ -0,0 +1,245 @@
+#define MS_CLASS "RTC::BWE::RobustThroughputEstimator"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/RobustThroughputEstimator.hpp"
+#include "Logger.hpp"
+#include <cmath>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Static. */
+
+		// Difference between arrival times beyond which the window is dropped, since
+		// such a jump means either severe reordering or that the remote clock moved.
+		static constexpr int64_t MaxReorderingTimeUs{ 1000 * 1000 };
+		// Smallest duration a rate is computed over, which keeps the division from
+		// blowing up when every packet of the window shares a timestamp.
+		static constexpr int64_t MinDurationUs{ 1000 };
+
+		/* Instance methods. */
+
+		RobustThroughputEstimator::RobustThroughputEstimator()
+		  : RobustThroughputEstimator(RobustThroughputEstimatorOptions{})
+		{
+			MS_TRACE();
+		}
+
+		RobustThroughputEstimator::RobustThroughputEstimator(RobustThroughputEstimatorOptions options)
+		  : options(options)
+		{
+			MS_TRACE();
+		}
+
+		void RobustThroughputEstimator::IncomingPacketFeedbackVector(
+		  const std::vector<Types::PacketResult>& packetResults)
+		{
+			MS_TRACE();
+
+			MS_ASSERT(
+			  std::ranges::is_sorted(packetResults, Types::PacketResult::ReceiveTimeOrder()),
+			  "packets are not sorted by arrival time");
+
+			for (const auto& packetResult : packetResults)
+			{
+				// Ignore the packets without a valid send or arrival time. It shouldn't
+				// happen, since the lost ones are filtered out before reaching here, but
+				// handling it explicitly avoids a state that would be hard to diagnose.
+				if (!packetResult.IsReceived() || packetResult.sentPacket.sendTimeUs == Types::TimeUsInfinite)
+				{
+					continue;
+				}
+
+				this->window.push_back(packetResult);
+
+				this->window.back().sentPacket.priorUnackedData = static_cast<size_t>(std::llround(
+				  static_cast<double>(this->window.back().sentPacket.priorUnackedData) *
+				  this->options.unackedWeight));
+
+				// Arrival times are usually already in order, but a reordered feedback
+				// needs a few swaps to keep the window sorted.
+				for (size_t idx = this->window.size() - 1;
+				     idx > 0 && this->window[idx].receiveTimeUs < this->window[idx - 1].receiveTimeUs;
+				     --idx)
+				{
+					std::swap(this->window[idx], this->window[idx - 1]);
+				}
+
+				const int64_t receiveDeltaUs =
+				  // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+				  this->window.back().receiveTimeUs.value() - packetResult.receiveTimeUs.value();
+
+				if (receiveDeltaUs > MaxReorderingTimeUs)
+				{
+					MS_WARN_TAG(
+					  bwe,
+					  "severe packet reordering or arrival time offset changed, dropping the window"
+					  " [receiveDelta:%" PRIi64 " us]",
+					  receiveDeltaUs);
+
+					this->window.clear();
+
+					this->latestDiscardedSendTimeUs.reset();
+				}
+			}
+
+			// Remove the packets that no longer belong to the window.
+			while (IsFirstPacketOutsideWindow())
+			{
+				this->latestDiscardedSendTimeUs = std::max(
+				  this->latestDiscardedSendTimeUs.value_or(this->window.front().sentPacket.sendTimeUs),
+				  this->window.front().sentPacket.sendTimeUs);
+
+				this->window.pop_front();
+			}
+		}
+
+		bool RobustThroughputEstimator::IsFirstPacketOutsideWindow() const
+		{
+			MS_TRACE();
+
+			if (this->window.empty())
+			{
+				return false;
+			}
+
+			if (this->window.size() > this->options.maxWindowPackets)
+			{
+				return true;
+			}
+
+			const int64_t currentWindowDurationUs =
+			  // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+			  this->window.back().receiveTimeUs.value() - this->window.front().receiveTimeUs.value();
+
+			if (currentWindowDurationUs > this->options.maxWindowDurationUs)
+			{
+				return true;
+			}
+
+			return this->window.size() > this->options.windowPackets &&
+			       currentWindowDurationUs > this->options.minWindowDurationUs;
+		}
+
+		std::optional<int64_t> RobustThroughputEstimator::GetBitrate() const
+		{
+			MS_TRACE();
+
+			if (this->window.empty() || this->window.size() < this->options.requiredPackets)
+			{
+				return std::nullopt;
+			}
+
+			int64_t largestRecvGapUs{ 0 };
+			int64_t secondLargestRecvGapUs{ 0 };
+
+			for (size_t idx = 1; idx < this->window.size(); ++idx)
+			{
+				const int64_t gapUs =
+				  // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+				  this->window[idx].receiveTimeUs.value() - this->window[idx - 1].receiveTimeUs.value();
+
+				if (gapUs > largestRecvGapUs)
+				{
+					secondLargestRecvGapUs = largestRecvGapUs;
+					largestRecvGapUs       = gapUs;
+				}
+				else if (gapUs > secondLargestRecvGapUs)
+				{
+					secondLargestRecvGapUs = gapUs;
+				}
+			}
+
+			std::optional<int64_t> firstSendTimeUs;
+			std::optional<int64_t> lastSendTimeUs;
+			std::optional<int64_t> firstRecvTimeUs;
+			std::optional<int64_t> lastRecvTimeUs;
+			int64_t recvSize{ 0 };
+			int64_t sendSize{ 0 };
+			int64_t firstRecvSize{ 0 };
+			int64_t lastSendSize{ 0 };
+			size_t numSentPacketsInWindow{ 0 };
+
+			for (const auto& packetResult : this->window)
+			{
+				// NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+				const int64_t receiveTimeUs = packetResult.receiveTimeUs.value();
+
+				if (!firstRecvTimeUs.has_value() || receiveTimeUs < firstRecvTimeUs.value())
+				{
+					firstRecvTimeUs = receiveTimeUs;
+					firstRecvSize   = packetResult.sentPacket.size + packetResult.sentPacket.priorUnackedData;
+				}
+
+				lastRecvTimeUs = std::max(lastRecvTimeUs.value_or(receiveTimeUs), receiveTimeUs);
+
+				recvSize += packetResult.sentPacket.size;
+				recvSize += packetResult.sentPacket.priorUnackedData;
+
+				// Packets sent before something that was already dropped from the window
+				// were reordered, and their send time may be so far in the past that it
+				// would drag the send rate down. Leave them out of it.
+				if (
+				  this->latestDiscardedSendTimeUs.has_value() &&
+				  packetResult.sentPacket.sendTimeUs < this->latestDiscardedSendTimeUs.value())
+				{
+					continue;
+				}
+
+				if (!lastSendTimeUs.has_value() || packetResult.sentPacket.sendTimeUs > lastSendTimeUs.value())
+				{
+					lastSendTimeUs = packetResult.sentPacket.sendTimeUs;
+					lastSendSize   = packetResult.sentPacket.size + packetResult.sentPacket.priorUnackedData;
+				}
+
+				firstSendTimeUs = std::min(
+				  firstSendTimeUs.value_or(packetResult.sentPacket.sendTimeUs),
+				  packetResult.sentPacket.sendTimeUs);
+
+				sendSize += packetResult.sentPacket.size;
+				sendSize += packetResult.sentPacket.priorUnackedData;
+
+				++numSentPacketsInWindow;
+			}
+
+			// Suppose a packet of size S is sent every T microseconds. A window of N
+			// packets holds N*S bytes, but the time between the first and the last one
+			// is only (N-1)*T, so one packet has to be left out to get the rate S/T.
+			// Which one depends on the direction: the receive rate doesn't depend on
+			// the size of the first packet, and the send rate doesn't depend on the
+			// size of the last one.
+			recvSize -= firstRecvSize;
+			sendSize -= lastSendSize;
+
+			// Replace the largest gap by the second largest one, so that a short pause
+			// followed by a burst of delayed packets doesn't drop the estimate. That
+			// can overestimate, which is guarded against by never returning more than
+			// the send rate.
+			MS_ASSERT(firstRecvTimeUs.has_value(), "no arrival time in a non empty window");
+			MS_ASSERT(lastRecvTimeUs.has_value(), "no arrival time in a non empty window");
+
+			const int64_t recvDurationUs = std::max(
+			  // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+			  (lastRecvTimeUs.value() - firstRecvTimeUs.value()) - largestRecvGapUs + secondLargestRecvGapUs,
+			  MinDurationUs);
+
+			if (numSentPacketsInWindow < this->options.requiredPackets)
+			{
+				// Too few send times to compute a reliable send rate.
+				return recvSize * 8 * 1000000 / recvDurationUs;
+			}
+
+			MS_ASSERT(firstSendTimeUs.has_value(), "no send time although packets were counted");
+			MS_ASSERT(lastSendTimeUs.has_value(), "no send time although packets were counted");
+
+			const int64_t sendDurationUs = std::max(
+			  // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+			  lastSendTimeUs.value() - firstSendTimeUs.value(),
+			  MinDurationUs);
+
+			return std::min(
+			  sendSize * 8 * 1000000 / sendDurationUs, recvSize * 8 * 1000000 / recvDurationUs);
+		}
+	} // namespace BWE
+} // namespace RTC

package/worker/src/RTC/BWE/SendPacketHistory.cpp

@@ -0,0 +1,184 @@
+#define MS_CLASS "RTC::BWE::SendPacketHistory"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/SendPacketHistory.hpp"
+#include "Logger.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Instance methods. */
+
+		SendPacketHistory::SendPacketHistory() : SendPacketHistory(SendPacketHistoryOptions{})
+		{
+			MS_TRACE();
+		}
+
+		SendPacketHistory::SendPacketHistory(SendPacketHistoryOptions options) : options(options)
+		{
+			MS_TRACE();
+		}
+
+		int64_t SendPacketHistory::AddPacket(
+		  uint32_t ssrc, uint16_t seq, size_t size, bool audio, int64_t sentAtUs)
+		{
+			MS_TRACE();
+
+			// Drop the packets held for longer than the window, since a feedback
+			// reporting on them is not of any use anymore.
+			while (!this->history.empty() && sentAtUs - this->history.begin()->second.sentPacket.sendTimeUs >
+			                                   this->options.windowDurationUs)
+			{
+				const auto& entry = this->history.begin()->second;
+
+				// Only the packets that no feedback has reported on yet count as in
+				// flight, since those already reported had their bytes removed then.
+				if (entry.sentPacket.sequenceNumber > this->lastAckSequenceNumber)
+				{
+					RemoveOutstandingBytes(entry);
+				}
+
+				RemoveSsrcAndSeq(entry);
+
+				this->history.erase(this->history.begin());
+			}
+
+			const int64_t sequenceNumber = this->nextSequenceNumber++;
+
+			SentPacketEntry entry;
+
+			entry.sentPacket.sequenceNumber = sequenceNumber;
+			entry.sentPacket.sendTimeUs     = sentAtUs;
+			entry.sentPacket.size           = size;
+			entry.sentPacket.audio          = audio;
+			entry.ssrc                      = ssrc;
+			entry.seq                       = seq;
+
+			// The very same SSRC and RTP sequence number can be sent twice, as an audio
+			// retransmission does, so let the latest send take the mapping over.
+			this->ssrcAndSeqToSequenceNumber[SsrcAndSeq{ .ssrc = ssrc, .seq = seq }] = sequenceNumber;
+
+			this->outstandingBytes += size;
+
+			entry.sentPacket.dataInFlight = this->outstandingBytes;
+
+			this->history.emplace(sequenceNumber, entry);
+
+			return sequenceNumber;
+		}
+
+		std::optional<Types::SentPacket> SendPacketHistory::RetrievePacket(
+		  int64_t sequenceNumber, bool received)
+		{
+			MS_TRACE();
+
+			// A sequence number this history never gave out cannot be resolved, and
+			// must not move the acknowledged mark either.
+			if (sequenceNumber < 0 || sequenceNumber >= this->nextSequenceNumber)
+			{
+				MS_DEBUG_DEV(
+				  "sequence number was never given out [sequenceNumber:%" PRIi64 "]", sequenceNumber);
+
+				return std::nullopt;
+			}
+
+			// The feedback settles whether every packet up to the reported one arrived
+			// or not, so none of them is in flight anymore.
+			if (sequenceNumber > this->lastAckSequenceNumber)
+			{
+				for (auto it = this->history.upper_bound(this->lastAckSequenceNumber);
+				     it != this->history.upper_bound(sequenceNumber);
+				     ++it)
+				{
+					RemoveOutstandingBytes(it->second);
+				}
+
+				this->lastAckSequenceNumber = sequenceNumber;
+			}
+
+			const auto it = this->history.find(sequenceNumber);
+
+			if (it == this->history.end())
+			{
+				// Either the window already dropped it or a previous feedback reported it
+				// as received.
+				MS_DEBUG_DEV("packet not held anymore [sequenceNumber:%" PRIi64 "]", sequenceNumber);
+
+				return std::nullopt;
+			}
+
+			const auto sentPacket = it->second.sentPacket;
+
+			// A packet reported as lost is kept, since a later feedback may still
+			// report it as received.
+			if (received)
+			{
+				RemoveSsrcAndSeq(it->second);
+
+				this->history.erase(it);
+			}
+
+			return sentPacket;
+		}
+
+		std::optional<Types::SentPacket> SendPacketHistory::RetrievePacket(
+		  uint32_t ssrc, uint16_t seq, bool received)
+		{
+			MS_TRACE();
+
+			const auto it = this->ssrcAndSeqToSequenceNumber.find(SsrcAndSeq{ .ssrc = ssrc, .seq = seq });
+
+			if (it == this->ssrcAndSeqToSequenceNumber.end())
+			{
+				MS_DEBUG_DEV("packet not held anymore [ssrc:%" PRIu32 ", seq:%" PRIu16 "]", ssrc, seq);
+
+				return std::nullopt;
+			}
+
+			return RetrievePacket(it->second, received);
+		}
+
+		std::optional<int64_t> SendPacketHistory::GetLastSequenceNumber() const
+		{
+			MS_TRACE();
+
+			if (this->nextSequenceNumber == 0)
+			{
+				return std::nullopt;
+			}
+
+			return this->nextSequenceNumber - 1;
+		}
+
+		void SendPacketHistory::RemoveOutstandingBytes(const SentPacketEntry& entry)
+		{
+			MS_TRACE();
+
+			// The acknowledged mark only moves forward, so the bytes of a packet are
+			// removed at most once.
+			MS_ASSERT(
+			  this->outstandingBytes >= entry.sentPacket.size,
+			  "less bytes in flight than the size of the packet being removed");
+
+			this->outstandingBytes -= entry.sentPacket.size;
+		}
+
+		void SendPacketHistory::RemoveSsrcAndSeq(const SentPacketEntry& entry)
+		{
+			MS_TRACE();
+
+			const auto it =
+			  this->ssrcAndSeqToSequenceNumber.find(SsrcAndSeq{ .ssrc = entry.ssrc, .seq = entry.seq });
+
+			// A later send of the very same SSRC and RTP sequence number took the
+			// mapping over, so it's not this packet's to drop.
+			if (it == this->ssrcAndSeqToSequenceNumber.end() || it->second != entry.sentPacket.sequenceNumber)
+			{
+				return;
+			}
+
+			this->ssrcAndSeqToSequenceNumber.erase(it);
+		}
+	} // namespace BWE
+} // namespace RTC