mediasoup 3.27.0 → 3.28.0

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

@@ -3,6 +3,7 @@
 
 #include "RTC/BWE/AimdRateControl.hpp"
 #include "Logger.hpp"
+#include "RTC/Consts.hpp"
 #include <cmath>
 
 namespace RTC
@@ -21,8 +22,6 @@ namespace RTC
 		// Bounds of how often the bitrate may be reduced, derived from the RTT.
 		static constexpr int64_t MinBitrateReductionIntervalUs{ 10 * 1000 };
 		static constexpr int64_t MaxBitrateReductionIntervalUs{ 200 * 1000 };
-		// Bitrate the target is never taken below unless configured otherwise (bps).
-		static constexpr int64_t CongestionControllerMinBitrate{ 5000 };
 		// Bitrate the target starts from before anything has been measured (bps).
 		static constexpr int64_t MaxConfiguredBitrate{ 30000 * 1000 };
 		// Headroom allowed on top of the measured throughput when increasing (bps).
@@ -64,7 +63,7 @@ namespace RTC
 
 		AimdRateControl::AimdRateControl(AimdRateControlOptions options)
 		  : options(options),
-		    minConfiguredBitrate(CongestionControllerMinBitrate),
+		    minConfiguredBitrate(Consts::BweMinBitrate),
 		    maxConfiguredBitrate(MaxConfiguredBitrate),
 		    currentBitrate(this->maxConfiguredBitrate),
 		    latestEstimatedThroughput(this->currentBitrate),
@@ -358,7 +357,7 @@ namespace RTC
 					break;
 				}
 
-					NO_DEFAULT_GCC();
+					NO_DEFAULT();
 			}
 
 			this->currentBitrate = ClampBitrate(newBitrate.value_or(this->currentBitrate));
@@ -398,7 +397,7 @@ namespace RTC
 					break;
 				}
 
-					NO_DEFAULT_GCC();
+					NO_DEFAULT();
 			}
 		}
 

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

@@ -0,0 +1,80 @@
+#define MS_CLASS "RTC::BWE::AlrDetector"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/AlrDetector.hpp"
+#include "Logger.hpp"
+#include "RTC/BWE/BitrateUtils.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Instance methods. */
+
+		AlrDetector::AlrDetector(SharedInterface* shared) : AlrDetector(shared, AlrDetectorOptions{})
+		{
+			MS_TRACE();
+		}
+
+		AlrDetector::AlrDetector(SharedInterface* shared, AlrDetectorOptions options)
+		  : shared(shared),
+		    options(options),
+		    // What an interval leaves unspent builds up, since not filling the link
+		    // is precisely a state that has to accumulate to be noticed.
+		    alrBudget(/*initialTargetBitrate*/ 0, /*canBuildUpUnderuse*/ true)
+		{
+			MS_TRACE();
+		}
+
+		void AlrDetector::OnBytesSent(int64_t bytesSent, int64_t sentAtUs)
+		{
+			MS_TRACE();
+
+			// How long those bytes took to go out is unknown until there is a previous
+			// send to measure them against.
+			if (!this->lastSentAtUs.has_value())
+			{
+				this->lastSentAtUs = sentAtUs;
+
+				return;
+			}
+
+			const int64_t deltaTimeUs = sentAtUs - this->lastSentAtUs.value();
+
+			this->lastSentAtUs = sentAtUs;
+
+			this->alrBudget.UseBudget(bytesSent);
+			this->alrBudget.IncreaseBudget(deltaTimeUs);
+
+			const double budgetRatio = this->alrBudget.GetBudgetRatio();
+
+			if (budgetRatio > this->options.startBudgetLevelRatio && !this->alrStartTimeUs.has_value())
+			{
+				// The instant this state began is what the rest of the module reasons
+				// about, so it's the current one and not that of the send that revealed
+				// it.
+				this->alrStartTimeUs = this->shared->GetTimeUs();
+
+				MS_DEBUG_DEV("sender is not filling the link [budgetRatio:%f]", budgetRatio);
+			}
+			else if (budgetRatio < this->options.stopBudgetLevelRatio && this->alrStartTimeUs.has_value())
+			{
+				this->alrStartTimeUs.reset();
+
+				MS_DEBUG_DEV("sender is filling the link again [budgetRatio:%f]", budgetRatio);
+			}
+		}
+
+		void AlrDetector::SetEstimatedBitrate(int64_t bitrate)
+		{
+			MS_TRACE();
+
+			// NOTE: The target this comes from is clamped to the minimum bitrate of
+			// the congestion controller, so anything else is a programming error.
+			MS_ASSERT(bitrate > 0, "bitrate must be positive [bitrate:%" PRIi64 "]", bitrate);
+
+			this->alrBudget.SetTargetBitrate(
+			  BitrateUtils::ApplyBitrateFactor(bitrate, this->options.bandwidthUsageRatio));
+		}
+	} // namespace BWE
+} // namespace RTC

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

@@ -0,0 +1,256 @@
+#define MS_CLASS "RTC::BWE::BitrateProber"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/BitrateProber.hpp"
+#include "Logger.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Static. */
+
+		// How long a burst that was asked for but never started is worth keeping.
+		static constexpr int64_t ProbeClusterTimeoutUs{ 5 * 1000 * 1000 };
+		// How many bursts may be waiting at once.
+		static constexpr size_t MaxPendingProbeClusters{ 5 };
+
+		/* Instance methods. */
+
+		BitrateProber::BitrateProber() : BitrateProber(BitrateProberOptions{})
+		{
+			MS_TRACE();
+		}
+
+		BitrateProber::BitrateProber(BitrateProberOptions options) : options(options)
+		{
+			MS_TRACE();
+		}
+
+		void BitrateProber::CreateProbeCluster(const Types::ProbeClusterConfig& clusterConfig)
+		{
+			MS_TRACE();
+
+			// NOTE: Whoever puts a burst configuration together already refuses a zero
+			// there, since it is what the bitrate of the burst is held over to decide
+			// how many bytes each of its shots carries.
+			MS_ASSERT(clusterConfig.minProbeDeltaUs > 0, "no time between packets of the burst");
+
+			// Whatever was asked for long ago is not worth sending anymore, and only so
+			// many may be waiting at once.
+			while (!this->clusters.empty() &&
+			       (clusterConfig.atUs - this->clusters.front().requestedAtUs > ProbeClusterTimeoutUs ||
+			        this->clusters.size() > MaxPendingProbeClusters))
+			{
+				this->clusters.pop();
+			}
+
+			Cluster cluster;
+
+			cluster.probeCluster.id        = clusterConfig.id;
+			cluster.probeCluster.minProbes = clusterConfig.targetProbeCount;
+			// The bytes the burst is meant to carry are its bitrate held for as long as
+			// it is meant to last, rounded to the nearest byte.
+			cluster.probeCluster.minBytes =
+			  ((clusterConfig.targetBitrate * clusterConfig.targetDurationUs) + 4000000) / (8 * 1000000);
+			cluster.sendBitrate     = clusterConfig.targetBitrate;
+			cluster.minProbeDeltaUs = clusterConfig.minProbeDeltaUs;
+			cluster.requestedAtUs   = clusterConfig.atUs;
+
+			MS_ASSERT(cluster.probeCluster.minBytes >= 0, "burst of a negative count of bytes");
+
+			this->clusters.push(cluster);
+
+			MaybeSetActiveState(/*packetSize*/ 0);
+
+			MS_DEBUG_DEV(
+			  "probe cluster created [id:%" PRIi64 ", bitrate:%" PRIi64 ", minBytes:%" PRIi64
+			  ", minProbes:%" PRIi64 ", active:%s]",
+			  cluster.probeCluster.id,
+			  cluster.sendBitrate,
+			  cluster.probeCluster.minBytes,
+			  cluster.probeCluster.minProbes,
+			  this->state == State::ACTIVE ? "true" : "false");
+		}
+
+		std::optional<int64_t> BitrateProber::GetNextProbeTimeUs(int64_t nowUs) const
+		{
+			MS_TRACE();
+
+			// Nothing is being emitted, or everything asked for is already done.
+			if (this->state != State::ACTIVE || this->clusters.empty())
+			{
+				return std::nullopt;
+			}
+
+			// A burst that hasn't started goes out at the first chance there is.
+			return this->nextProbeTimeUs.value_or(nowUs);
+		}
+
+		std::optional<BitrateProber::CurrentCluster> BitrateProber::GetCurrentCluster(int64_t nowUs)
+		{
+			MS_TRACE();
+
+			if (this->clusters.empty() || this->state != State::ACTIVE)
+			{
+				return std::nullopt;
+			}
+
+			// A packet that goes out long after it was due no longer measures the
+			// bitrate the burst was meant to be sent at, so the whole burst is dropped
+			// rather than believed.
+			if (this->nextProbeTimeUs.has_value() && nowUs - this->nextProbeTimeUs.value() > this->options.maxProbeDelayUs)
+			{
+				MS_DEBUG_DEV(
+				  "probe delayed too much, discarding the cluster [dueAt:%" PRIi64 ", now:%" PRIi64 "]",
+				  this->nextProbeTimeUs.value(),
+				  nowUs);
+
+				this->clusters.pop();
+
+				if (this->clusters.empty())
+				{
+					this->state = State::INACTIVE;
+
+					return std::nullopt;
+				}
+			}
+
+			const auto& cluster = this->clusters.front();
+
+			return CurrentCluster{ .probeCluster = cluster.probeCluster, .sentBytes = cluster.sentBytes };
+		}
+
+		size_t BitrateProber::GetRecommendedMinProbeSize() const
+		{
+			MS_TRACE();
+
+			if (this->clusters.empty())
+			{
+				return 0;
+			}
+
+			const auto& cluster = this->clusters.front();
+
+			// What the burst's bitrate carries over the time between two of its shots,
+			// rounded to the nearest byte.
+			return static_cast<size_t>(
+			  ((cluster.sendBitrate * cluster.minProbeDeltaUs) + 4000000) / (8 * 1000000));
+		}
+
+		void BitrateProber::ProbeSent(int64_t nowUs, size_t size)
+		{
+			MS_TRACE();
+
+			// NOTE: Reporting a shot means one was asked for with GetCurrentCluster(),
+			// which only answers while a burst is being emitted, and that state is
+			// only left from within this class.
+			MS_ASSERT(this->state == State::ACTIVE, "no burst is being emitted");
+			// NOTE: A shot out of which no byte left is not reported at all, since
+			// there would be nothing to measure the burst with.
+			MS_ASSERT(size != 0, "a packet of no bytes was sent");
+
+			if (this->clusters.empty())
+			{
+				return;
+			}
+
+			auto& cluster = this->clusters.front();
+
+			if (cluster.sentProbes == 0)
+			{
+				MS_ASSERT(!cluster.startedAtUs.has_value(), "burst already started");
+
+				cluster.startedAtUs = nowUs;
+			}
+
+			cluster.sentBytes += static_cast<int64_t>(size);
+			cluster.sentProbes += 1;
+
+			this->nextProbeTimeUs = CalculateNextProbeTimeUs(cluster);
+
+			// Both counts have to be reached, since a burst of too few packets says
+			// nothing however many bytes it carried, and the other way round.
+			if (
+			  cluster.sentBytes >= cluster.probeCluster.minBytes &&
+			  cluster.sentProbes >= cluster.probeCluster.minProbes)
+			{
+				this->clusters.pop();
+			}
+
+			if (this->clusters.empty())
+			{
+				this->state = State::INACTIVE;
+			}
+		}
+
+		void BitrateProber::OnIncomingPacket(size_t packetSize)
+		{
+			MS_TRACE();
+
+			MaybeSetActiveState(packetSize);
+		}
+
+		void BitrateProber::MaybeSetActiveState(size_t packetSize)
+		{
+			MS_TRACE();
+
+			if (IsReadyToSetActiveState(packetSize))
+			{
+				this->nextProbeTimeUs.reset();
+				this->state = State::ACTIVE;
+			}
+		}
+
+		bool BitrateProber::IsReadyToSetActiveState(size_t packetSize) const
+		{
+			MS_TRACE();
+
+			if (this->clusters.empty())
+			{
+				MS_ASSERT(this->state == State::INACTIVE, "emitting a burst with none to emit");
+
+				return false;
+			}
+
+			switch (this->state)
+			{
+				case State::ACTIVE:
+				{
+					return false;
+				}
+
+				case State::INACTIVE:
+				{
+					if (this->options.allowStartProbingImmediately)
+					{
+						return true;
+					}
+
+					// A burst that begins on a tiny packet starts measuring from an instant
+					// that says nothing, so a big enough one has to go out first. What
+					// counts as big enough is never more than a whole shot of the burst.
+					return packetSize >= std::min(GetRecommendedMinProbeSize(), this->options.minPacketSize);
+				}
+			}
+
+			return false;
+		}
+
+		int64_t BitrateProber::CalculateNextProbeTimeUs(const Cluster& cluster) const
+		{
+			MS_TRACE();
+
+			MS_ASSERT(cluster.sendBitrate > 0, "burst at no bitrate");
+			MS_ASSERT(cluster.startedAtUs.has_value(), "burst has not started");
+
+			// Measured from the start of the burst rather than from the previous packet,
+			// so that a packet going out late is made up for by the ones after it
+			// instead of dragging the whole burst below the bitrate asked for.
+			const int64_t deltaUs = (cluster.sentBytes * 8 * 1000000) / cluster.sendBitrate;
+
+			// NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+			return cluster.startedAtUs.value() + deltaUs;
+		}
+	} // namespace BWE
+} // namespace RTC

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

@@ -0,0 +1,54 @@
+#define MS_CLASS "RTC::BWE::BitrateUtils"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/BitrateUtils.hpp"
+#include "Logger.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include <cmath> // std::llround()
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Class methods. */
+
+		int64_t BitrateUtils::ApplyBitrateFactor(int64_t bitrate, double factor)
+		{
+			MS_TRACE();
+
+			const double result = static_cast<double>(bitrate) * factor;
+
+			// NOTE: Converting a value that the type cannot hold is undefined
+			// behaviour, and the maximum bitrate is chosen by the application, so
+			// nothing keeps this product within range.
+			if (result >= static_cast<double>(Types::BitrateInfinite))
+			{
+				return Types::BitrateInfinite;
+			}
+
+			if (result <= 0.0)
+			{
+				return 0;
+			}
+
+			// The result is rounded rather than truncated, since a factor is applied
+			// over and over to a bitrate that keeps being derived from the previous
+			// one and always losing the fraction drifts it downwards.
+			return std::llround(result);
+		}
+
+		int64_t BitrateUtils::AddBitrates(int64_t bitrate, int64_t otherBitrate)
+		{
+			MS_TRACE();
+
+			// NOTE: Signed overflow is undefined behaviour, and both operands can be
+			// as high as the application allows.
+			if (bitrate > Types::BitrateInfinite - otherBitrate)
+			{
+				return Types::BitrateInfinite;
+			}
+
+			return bitrate + otherBitrate;
+		}
+	} // namespace BWE
+} // namespace RTC

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

@@ -110,7 +110,7 @@ namespace RTC
 
 			if (this->options.separateAudioPackets)
 			{
-				if (packetResult.sentPacket.audio)
+				if (packetResult.sentPacket.isAudio)
 				{
 					// NOLINTNEXTLINE(bugprone-unchecked-optional-access)
 					delayDetectorForPacket = std::addressof(this->audioDelayDetector.value());
@@ -141,7 +141,7 @@ namespace RTC
 			}
 
 			auto& interArrivalForPacket =
-			  (this->options.separateAudioPackets && packetResult.sentPacket.audio)
+			  (this->options.separateAudioPackets && packetResult.sentPacket.isAudio)
 			    // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
 			    ? this->audioInterArrivalDelta.value()
 			    // NOLINTNEXTLINE(bugprone-unchecked-optional-access)

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

@@ -28,17 +28,6 @@ namespace RTC
 				return std::nullopt;
 			}
 
-			const auto lastSequenceNumber = this->sendPacketHistory->GetLastSequenceNumber();
-
-			if (!lastSequenceNumber.has_value())
-			{
-				MS_DEBUG_TAG(bwe, "feedback received before any packet was sent");
-
-				return std::nullopt;
-			}
-
-			const int64_t lastSentSequenceNumber = lastSequenceNumber.value();
-
 			const int64_t baseTimeUs = feedback->GetReferenceTimestampUs();
 
 			if (!this->lastFeedbackBaseTimeUs.has_value())
@@ -47,6 +36,10 @@ namespace RTC
 			}
 			else
 			{
+				// NOTE: Taken in microseconds and not quantized any further. The groups
+				// whose arrival times the delay detector compares are only a few
+				// milliseconds apart, so rounding them to whole milliseconds would be
+				// noise of the same order as the slope being measured.
 				const int64_t baseDeltaUs = feedback->GetBaseDeltaUs(this->lastFeedbackBaseTimeUs.value());
 
 				if (baseDeltaUs < -this->currentOffsetUs)
@@ -76,30 +69,35 @@ namespace RTC
 
 			size_t failedLookups{ 0 };
 
-			// Each packet is resolved against the one reported before it, since the
-			// packets being sent may be far ahead of the ones the feedbacks report on.
-			// The latest packet sent seeds it, and bounds it as well, since no report
-			// can stand for a packet that was never sent.
-			int64_t sequenceNumber = std::min(
-			  this->lastUnwrappedSequenceNumber.value_or(lastSentSequenceNumber), lastSentSequenceNumber);
-
 			for (const auto& packetStatus : packetStatuses)
 			{
-				sequenceNumber = UnwrapSequenceNumber(packetStatus.sequenceNumber, sequenceNumber);
+				// The wire carries the sequence number of the transport truncated to 16
+				// bits, so it's the history, which handed it out, the one that knows
+				// which of its packets it stands for.
+				const int64_t sequenceNumber =
+				  this->sendPacketHistory->UnwrapSequenceNumber(packetStatus.sequenceNumber);
 
-				const auto sentPacket =
+				const auto retrievedEntry =
 				  this->sendPacketHistory->RetrievePacket(sequenceNumber, packetStatus.received);
 
-				if (!sentPacket.has_value())
+				if (!retrievedEntry.has_value())
 				{
 					++failedLookups;
 
 					continue;
 				}
 
+				const auto& entry = retrievedEntry.value();
+
 				Types::PacketResult packetResult;
 
-				packetResult.sentPacket = sentPacket.value();
+				packetResult.sentPacket = entry.sentPacket;
+				packetResult.rtpPacketInfo =
+				  Types::PacketResult::RtpPacketInfo{ .ssrc              = entry.ssrc,
+					                                    .rtpSequenceNumber = entry.seq,
+					                                    .isRetransmission  = entry.isRetransmission };
+				packetResult.ambiguousReceiveTime = entry.ambiguousReceiveTime;
+				packetResult.sentWithEct1         = entry.sentWithEct1;
 
 				if (packetStatus.received)
 				{
@@ -110,8 +108,6 @@ namespace RTC
 				transportPacketsFeedback.packetFeedbacks.push_back(packetResult);
 			}
 
-			this->lastUnwrappedSequenceNumber = sequenceNumber;
-
 			if (failedLookups > 0)
 			{
 				MS_DEBUG_TAG(
@@ -131,18 +127,5 @@ namespace RTC
 			return transportPacketsFeedback;
 		}
 
-		int64_t FeedbackAdapter::UnwrapSequenceNumber(
-		  uint16_t wideSequenceNumber, int64_t previousSequenceNumber)
-		{
-			MS_TRACE();
-
-			// The wire carries the sequence number of the history truncated to 16 bits,
-			// so the closest value to the previous one ending in those very same bits
-			// is the one it stands for.
-			const auto deltaSequenceNumber = static_cast<int16_t>(
-			  static_cast<uint16_t>(wideSequenceNumber - static_cast<uint16_t>(previousSequenceNumber)));
-
-			return previousSequenceNumber + deltaSequenceNumber;
-		}
 	} // namespace BWE
 } // namespace RTC