mediasoup 3.26.0 → 3.27.0

package/worker/test/src/RTC/BWE/TestTrendlineEstimator.cpp

@@ -0,0 +1,137 @@
+#include "common.hpp"
+#include "RTC/BWE/TrendlineEstimator.hpp"
+#include <catch2/catch_test_macros.hpp>
+
+SCENARIO("BWE TrendlineEstimator", "[bwe][trendlineestimator]")
+{
+	// Number of packets a test is given.
+	constexpr size_t PacketCount{ 25 };
+	// Time between two consecutive groups of packets.
+	constexpr int64_t SendDeltaUs{ 20 * 1000 };
+	constexpr int64_t InitialArrivalTimeUs{ 987654321000 };
+
+	// Feed groups delivered at `deliveryPace` times the pace they were sent at,
+	// until the state changes or the packets are exhausted.
+	//
+	// Both `count` and `arrivalTimeUs` are shared by every run within a test, so
+	// that consecutive runs consume a single budget of packets and carry on from
+	// the network conditions left by the previous one.
+	auto runUntilStateChange = [](
+	                             RTC::BWE::TrendlineEstimator& trendlineEstimator,
+	                             double deliveryPace,
+	                             size_t& count,
+	                             size_t packetCount,
+	                             int64_t& arrivalTimeUs) -> void
+	{
+		const auto initialState   = trendlineEstimator.GetState();
+		const auto arrivalDeltaUs = static_cast<int64_t>(SendDeltaUs * deliveryPace);
+
+		for (; count < packetCount; ++count)
+		{
+			arrivalTimeUs += arrivalDeltaUs;
+
+			trendlineEstimator.Update(SendDeltaUs, arrivalDeltaUs, arrivalTimeUs);
+
+			if (trendlineEstimator.GetState() != initialState)
+			{
+				return;
+			}
+		}
+	};
+
+	SECTION("a network delivering at the pace it's fed stays in normal state")
+	{
+		RTC::BWE::TrendlineEstimator trendlineEstimator;
+		size_t count{ 1 };
+		int64_t arrivalTimeUs{ InitialArrivalTimeUs };
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::NORMAL);
+
+		runUntilStateChange(trendlineEstimator, /*deliveryPace*/ 1.0, count, PacketCount, arrivalTimeUs);
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::NORMAL);
+		// Every packet was processed, so the state never changed.
+		REQUIRE(count == PacketCount);
+	}
+
+	SECTION("a 10% slower delivery is detected as overusing")
+	{
+		RTC::BWE::TrendlineEstimator trendlineEstimator;
+		size_t count{ 1 };
+		int64_t arrivalTimeUs{ InitialArrivalTimeUs };
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::NORMAL);
+
+		runUntilStateChange(trendlineEstimator, /*deliveryPace*/ 1.1, count, PacketCount, arrivalTimeUs);
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::OVERUSING);
+
+		// The state is kept while the delay keeps growing.
+		runUntilStateChange(trendlineEstimator, /*deliveryPace*/ 1.1, count, PacketCount, arrivalTimeUs);
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::OVERUSING);
+		REQUIRE(count == PacketCount);
+	}
+
+	SECTION("a 15% faster delivery is detected as underusing")
+	{
+		RTC::BWE::TrendlineEstimator trendlineEstimator;
+		size_t count{ 1 };
+		int64_t arrivalTimeUs{ InitialArrivalTimeUs };
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::NORMAL);
+
+		runUntilStateChange(trendlineEstimator, /*deliveryPace*/ 0.85, count, PacketCount, arrivalTimeUs);
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::UNDERUSING);
+
+		// The state is kept while the delay keeps shrinking.
+		runUntilStateChange(trendlineEstimator, /*deliveryPace*/ 0.85, count, PacketCount, arrivalTimeUs);
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::UNDERUSING);
+		REQUIRE(count == PacketCount);
+	}
+
+	SECTION("an isolated delay spike is not detected as overusing")
+	{
+		RTC::BWE::TrendlineEstimator trendlineEstimator;
+		size_t count{ 1 };
+		int64_t arrivalTimeUs{ InitialArrivalTimeUs };
+
+		// Fill the regression window with a well behaved network.
+		runUntilStateChange(trendlineEstimator, /*deliveryPace*/ 1.0, count, PacketCount, arrivalTimeUs);
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::NORMAL);
+
+		// A single group arrives 50 ms late and the very next one recovers that same
+		// time, which is a jitter spike and not a queue that keeps growing.
+		arrivalTimeUs += SendDeltaUs + (50 * 1000);
+		trendlineEstimator.Update(SendDeltaUs, SendDeltaUs + (50 * 1000), arrivalTimeUs);
+
+		arrivalTimeUs += SendDeltaUs - (50 * 1000);
+		trendlineEstimator.Update(SendDeltaUs, SendDeltaUs - (50 * 1000), arrivalTimeUs);
+
+		// This is the hysteresis being tested: overuse requires the condition to
+		// persist over more than one sample.
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::NORMAL);
+	}
+
+	SECTION("recovers to normal once the delay stops growing")
+	{
+		RTC::BWE::TrendlineEstimator trendlineEstimator;
+		size_t count{ 1 };
+		int64_t arrivalTimeUs{ InitialArrivalTimeUs };
+
+		runUntilStateChange(
+		  trendlineEstimator, /*deliveryPace*/ 1.1, count, /*packetCount*/ 100, arrivalTimeUs);
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::OVERUSING);
+
+		// The delay stops growing but doesn't shrink either, so the accumulated
+		// delay flattens out and the slope goes back to zero.
+		runUntilStateChange(
+		  trendlineEstimator, /*deliveryPace*/ 1.0, count, /*packetCount*/ 100, arrivalTimeUs);
+
+		REQUIRE(trendlineEstimator.GetState() == RTC::BWE::Types::BandwidthUsage::NORMAL);
+	}
+}

package/worker/test/src/RTC/BWE/helpers/LinkSimulator.cpp

@@ -0,0 +1,171 @@
+#define MS_CLASS "test::bweHelpers::LinkSimulator"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "test/include/RTC/BWE/helpers/LinkSimulator.hpp"
+#include "Logger.hpp"
+
+namespace bweHelpers
+{
+	/* Static. */
+
+	// Largest packet a frame is split into (bytes).
+	static constexpr size_t Mtu{ 1200 };
+
+	/* Instance methods. */
+
+	RtpStream::RtpStream(int fps, int64_t bitrateBps) : fps(fps), bitrateBps(bitrateBps)
+	{
+		MS_TRACE();
+
+		MS_ASSERT(fps > 0, "fps must be greater than zero [fps:%d]", fps);
+	}
+
+	int64_t RtpStream::GenerateFrame(
+	  int64_t timeNowUs,
+	  int64_t& nextSequenceNumber,
+	  std::vector<RTC::BWE::Types::PacketResult>& packetResults)
+	{
+		MS_TRACE();
+
+		if (timeNowUs < this->nextRtpTimeUs)
+		{
+			return this->nextRtpTimeUs;
+		}
+
+		const size_t bitsPerFrame = (this->bitrateBps + (this->fps / 2)) / this->fps;
+		const size_t numPackets   = std::max<size_t>((bitsPerFrame + (4 * Mtu)) / (8 * Mtu), 1);
+		const size_t payloadSize  = (bitsPerFrame + (4 * numPackets)) / (8 * numPackets);
+
+		for (size_t idx{ 0 }; idx < numPackets; ++idx)
+		{
+			RTC::BWE::Types::PacketResult packetResult;
+
+			packetResult.sentPacket.sendTimeUs     = timeNowUs + SendSideOffsetUs;
+			packetResult.sentPacket.size           = payloadSize;
+			packetResult.sentPacket.sequenceNumber = nextSequenceNumber++;
+
+			packetResults.push_back(packetResult);
+		}
+
+		this->nextRtpTimeUs = timeNowUs + ((1000000 + (this->fps / 2)) / this->fps);
+
+		return this->nextRtpTimeUs;
+	}
+
+	void RtpStream::SetBitrateBps(int64_t bitrateBps)
+	{
+		MS_TRACE();
+
+		MS_ASSERT(bitrateBps >= 0, "bitrate must not be negative [bitrate:%" PRIi64 "]", bitrateBps);
+
+		this->bitrateBps = bitrateBps;
+	}
+
+	bool RtpStream::Compare(const std::unique_ptr<RtpStream>& lhs, const std::unique_ptr<RtpStream>& rhs)
+	{
+		MS_TRACE();
+
+		return lhs->nextRtpTimeUs < rhs->nextRtpTimeUs;
+	}
+
+	LinkSimulator::LinkSimulator(int64_t capacityBps, int64_t timeNowUs)
+	  : capacityBps(capacityBps), prevArrivalTimeUs(timeNowUs)
+	{
+		MS_TRACE();
+	}
+
+	void LinkSimulator::AddStream(std::unique_ptr<RtpStream> stream)
+	{
+		MS_TRACE();
+
+		this->streams.push_back(std::move(stream));
+	}
+
+	void LinkSimulator::SetCapacityBps(int64_t capacityBps)
+	{
+		MS_TRACE();
+
+		MS_ASSERT(
+		  capacityBps > 0, "capacity must be greater than zero [capacity:%" PRIi64 "]", capacityBps);
+
+		this->capacityBps = capacityBps;
+	}
+
+	void LinkSimulator::SetBitrateBps(int64_t bitrateBps)
+	{
+		MS_TRACE();
+
+		int64_t totalBitrateBefore{ 0 };
+
+		for (const auto& stream : this->streams)
+		{
+			totalBitrateBefore += stream->GetBitrateBps();
+		}
+
+		// The ratios each stream keeps are taken from what they add up to, so there
+		// has to be something to take them from.
+		MS_ASSERT(
+		  totalBitrateBefore > 0,
+		  "the streams add up to no bitrate at all [streams:%zu]",
+		  this->streams.size());
+
+		int64_t bitrateBefore{ 0 };
+		int64_t totalBitrateAfter{ 0 };
+
+		for (const auto& stream : this->streams)
+		{
+			bitrateBefore += stream->GetBitrateBps();
+
+			const int64_t bitrateAfter =
+			  ((bitrateBefore * bitrateBps) + (totalBitrateBefore / 2)) / totalBitrateBefore;
+
+			stream->SetBitrateBps(bitrateAfter - totalBitrateAfter);
+
+			totalBitrateAfter += stream->GetBitrateBps();
+		}
+
+		MS_ASSERT(
+		  totalBitrateAfter == bitrateBps,
+		  "the bitrate was not fully distributed [expected:%" PRIi64 ", distributed:%" PRIi64 "]",
+		  bitrateBps,
+		  totalBitrateAfter);
+	}
+
+	int64_t LinkSimulator::GenerateFrame(
+	  int64_t timeNowUs,
+	  int64_t& nextSequenceNumber,
+	  std::vector<RTC::BWE::Types::PacketResult>& packetResults)
+	{
+		MS_TRACE();
+
+		MS_ASSERT(packetResults.empty(), "the given vector is not empty");
+		MS_ASSERT(
+		  this->capacityBps > 0,
+		  "capacity must be greater than zero [capacity:%" PRIi64 "]",
+		  this->capacityBps);
+
+		auto it = std::ranges::min_element(this->streams, RtpStream::Compare);
+
+		(*it)->GenerateFrame(timeNowUs, nextSequenceNumber, packetResults);
+
+		for (auto& packetResult : packetResults)
+		{
+			// Time the link needs to put the packet on the wire.
+			const int64_t capacityBpUs = this->capacityBps / 1000;
+			const int64_t requiredNetworkTimeUs =
+			  ((8 * 1000 * static_cast<int64_t>(packetResult.sentPacket.size)) + (capacityBpUs / 2)) /
+			  capacityBpUs;
+
+			// A packet arrives once the link is free again, so it queues behind the
+			// previous one whenever the stream is sending above the capacity.
+			this->prevArrivalTimeUs =
+			  std::max(timeNowUs + requiredNetworkTimeUs, this->prevArrivalTimeUs + requiredNetworkTimeUs);
+
+			packetResult.receiveTimeUs = this->prevArrivalTimeUs;
+		}
+
+		it = std::ranges::min_element(this->streams, RtpStream::Compare);
+
+		return std::max((*it)->GetNextRtpTimeUs(), timeNowUs);
+	}
+} // namespace bweHelpers

package/worker/test/src/RTC/RTCP/TestFeedbackPsRemb.cpp

@@ -23,7 +23,7 @@ SCENARIO("RTCP Feedback PS REMB", "[rtcp][feedback-ps][remb]")
 	// REMB values.
 	const uint32_t senderSsrc{ 0xfa17fa17 };
 	const uint32_t mediaSsrc{ 0u };
-	const uint64_t bitrate{ 122754u };
+	const int64_t bitrate{ 122754 };
 	const std::vector<uint32_t> ssrcs{ 0x02d03702, 0x04a76747 };
 
 	// NOTE: No need to pass const integers to the lambda.

package/worker/test/src/RTC/RTCP/TestFeedbackRtpTmmb.cpp

@@ -22,7 +22,7 @@ SCENARIO("RTCP Feedback RTP TMMBR", "[rtcp][feedback-rtp][tmmb]")
 	const uint32_t senderSsrc{ 0x00000001 };
 	const uint32_t mediaSsrc{ 0x0330bdee };
 	const uint32_t ssrc{ 0x02d03702 };
-	const uint64_t bitrate{ 365504 };
+	const int64_t bitrate{ 365504 };
 	const uint16_t overhead{ 0 };
 
 	// NOTE: No need to pass const integers to the lambda.