mediasoup 3.27.0 → 3.28.0

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

@@ -0,0 +1,216 @@
+#define MS_CLASS "RTC::BWE::InterArrival"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/InterArrival.hpp"
+#include "Logger.hpp"
+#include "Utils.hpp"
+#include <cmath> // std::llround()
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Static. */
+
+		// Maximum arrival time delta for a packet to be absorbed into the ongoing
+		// burst.
+		static constexpr int64_t BurstDeltaThresholdUs{ 5000 };
+		// Maximum duration of a burst.
+		static constexpr int64_t MaxBurstDurationUs{ 100000 };
+		// Number of consecutive reordered groups after which the state is reset.
+		static constexpr size_t ReorderedResetThreshold{ 3 };
+		// Difference between the arrival time delta and our own time delta after
+		// which the state is reset, assuming that the remote clock has jumped.
+		static constexpr int64_t ArrivalTimeOffsetThresholdUs{ 3000000 };
+
+		/* Instance methods. */
+
+		InterArrival::InterArrival(uint32_t timestampGroupLengthTicks, double timestampToUsCoeff)
+		  : timestampGroupLengthTicks(timestampGroupLengthTicks), timestampToUsCoeff(timestampToUsCoeff)
+		{
+			MS_TRACE();
+		}
+
+		std::optional<InterArrival::Deltas> InterArrival::ComputeDeltas(
+		  uint32_t timestamp, int64_t arrivalTimeUs, int64_t systemTimeUs, size_t packetSize)
+		{
+			MS_TRACE();
+
+			std::optional<Deltas> deltas;
+
+			if (this->currentGroup.IsFirstPacket())
+			{
+				// Not enough data to compute deltas yet, so just store the packet until
+				// there are two groups to compare.
+				this->currentGroup.timestamp          = timestamp;
+				this->currentGroup.firstTimestamp     = timestamp;
+				this->currentGroup.firstArrivalTimeUs = arrivalTimeUs;
+			}
+			else if (!IsPacketInOrder(timestamp))
+			{
+				// Reordered packet.
+				return std::nullopt;
+			}
+			else if (IsNewTimestampGroup(arrivalTimeUs, timestamp))
+			{
+				// This is the first packet of a later send burst, so the sample of the
+				// ongoing group is ready.
+				if (!this->prevGroup.IsFirstPacket())
+				{
+					const uint32_t timestampDelta = this->currentGroup.timestamp - this->prevGroup.timestamp;
+					const int64_t arrivalDeltaUs =
+					  // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+					  this->currentGroup.completeTimeUs.value() -
+					  // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+					  this->prevGroup.completeTimeUs.value();
+					const int64_t ownDeltaUs =
+					  this->currentGroup.lastSystemTimeUs - this->prevGroup.lastSystemTimeUs;
+
+					if (arrivalDeltaUs - ownDeltaUs >= ArrivalTimeOffsetThresholdUs)
+					{
+						MS_WARN_TAG(
+						  bwe,
+						  "arrival time clock offset has changed, resetting [diff:%" PRIi64 " us]",
+						  arrivalDeltaUs - ownDeltaUs);
+
+						Reset();
+
+						return std::nullopt;
+					}
+
+					if (arrivalDeltaUs < 0)
+					{
+						// The groups have been reordered after their arrival time was taken.
+						++this->numConsecutiveReorderedGroups;
+
+						if (this->numConsecutiveReorderedGroups >= ReorderedResetThreshold)
+						{
+							MS_WARN_TAG(
+							  bwe,
+							  "packets between send bursts arrived out of order, resetting [arrivalDelta:%" PRIi64
+							  " us]",
+							  arrivalDeltaUs);
+
+							Reset();
+						}
+
+						return std::nullopt;
+					}
+
+					this->numConsecutiveReorderedGroups = 0;
+
+					// NOTE: Guaranteed by the branch right above, which returns for every
+					// negative one.
+					MS_ASSERT(arrivalDeltaUs >= 0, "arrival delta is negative");
+
+					deltas = Deltas{ .timestampDelta = timestampDelta,
+					                 .arrivalDeltaUs = arrivalDeltaUs,
+					                 .sizeDelta      = static_cast<int64_t>(this->currentGroup.size) -
+						                                 static_cast<int64_t>(this->prevGroup.size) };
+				}
+
+				this->prevGroup = this->currentGroup;
+
+				// The new packet starts the current group.
+				this->currentGroup.firstTimestamp     = timestamp;
+				this->currentGroup.timestamp          = timestamp;
+				this->currentGroup.firstArrivalTimeUs = arrivalTimeUs;
+				this->currentGroup.size               = 0;
+			}
+			else
+			{
+				// NOTE: Not std::max() because these timestamps wrap around, so the
+				// later one is not necessarily the greater one.
+				this->currentGroup.timestamp =
+				  Utils::Number::IsHigherThan<uint32_t>(timestamp, this->currentGroup.timestamp)
+				    ? timestamp
+				    : this->currentGroup.timestamp;
+			}
+
+			// Accumulate the group size.
+			this->currentGroup.size += packetSize;
+			this->currentGroup.completeTimeUs   = arrivalTimeUs;
+			this->currentGroup.lastSystemTimeUs = systemTimeUs;
+
+			return deltas;
+		}
+
+		bool InterArrival::IsPacketInOrder(uint32_t timestamp) const
+		{
+			MS_TRACE();
+
+			if (this->currentGroup.IsFirstPacket())
+			{
+				return true;
+			}
+
+			// A packet of the very same timestamp as the first one of the group is in
+			// order, so this is not a strict comparison.
+			return Utils::Number::IsHigherOrEqualThan<uint32_t>(
+			  timestamp, this->currentGroup.firstTimestamp);
+		}
+
+		bool InterArrival::IsNewTimestampGroup(int64_t arrivalTimeUs, uint32_t timestamp) const
+		{
+			MS_TRACE();
+
+			if (this->currentGroup.IsFirstPacket())
+			{
+				return false;
+			}
+			else if (BelongsToBurst(arrivalTimeUs, timestamp))
+			{
+				return false;
+			}
+			else
+			{
+				// NOTE: The subtraction is done in the width of the timestamps, so a
+				// group that spans their wrap around still measures its own length.
+				const uint32_t timestampDiff = timestamp - this->currentGroup.firstTimestamp;
+
+				return timestampDiff > this->timestampGroupLengthTicks;
+			}
+		}
+
+		bool InterArrival::BelongsToBurst(int64_t arrivalTimeUs, uint32_t timestamp) const
+		{
+			MS_TRACE();
+
+			MS_ASSERT(!this->currentGroup.IsFirstPacket(), "current group is empty");
+
+			const int64_t arrivalDeltaUs =
+			  // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+			  arrivalTimeUs - this->currentGroup.completeTimeUs.value();
+			const uint32_t timestampDiff = timestamp - this->currentGroup.timestamp;
+			const auto sendDeltaUs       = std::llround(this->timestampToUsCoeff * timestampDiff);
+
+			// Packets sent at the very same time always belong to the same burst.
+			//
+			// NOTE: Sameness is told apart with a resolution of a millisecond, which
+			// is the one every threshold of this path is expressed in. A finer one
+			// would leave packets that left together out of the burst just because
+			// the timestamps they carry can tell them apart.
+			if (std::llround(static_cast<double>(sendDeltaUs) / 1000.0) == 0)
+			{
+				return true;
+			}
+
+			const int64_t propagationDeltaUs = arrivalDeltaUs - sendDeltaUs;
+			const int64_t burstDurationUs    = arrivalTimeUs - this->currentGroup.firstArrivalTimeUs;
+
+			// The packet arrived earlier than its send time gap would suggest, meaning
+			// that it was serialized by the network together with the ongoing group.
+			return propagationDeltaUs < 0 && arrivalDeltaUs <= BurstDeltaThresholdUs &&
+			       burstDurationUs < MaxBurstDurationUs;
+		}
+
+		void InterArrival::Reset()
+		{
+			MS_TRACE();
+
+			this->numConsecutiveReorderedGroups = 0;
+			this->currentGroup                  = TimestampGroup();
+			this->prevGroup                     = TimestampGroup();
+		}
+	} // namespace BWE
+} // namespace RTC

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

@@ -0,0 +1,93 @@
+#define MS_CLASS "RTC::BWE::IntervalBudget"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/IntervalBudget.hpp"
+#include "Logger.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Static. */
+
+		// Span of time the budget is measured over.
+		static constexpr int64_t WindowUs{ 500 * 1000 };
+
+		/* Instance methods. */
+
+		IntervalBudget::IntervalBudget(int64_t initialTargetBitrate)
+		  : IntervalBudget(initialTargetBitrate, /*canBuildUpUnderuse*/ false)
+		{
+			MS_TRACE();
+		}
+
+		IntervalBudget::IntervalBudget(int64_t initialTargetBitrate, bool canBuildUpUnderuse)
+		  : canBuildUpUnderuse(canBuildUpUnderuse)
+		{
+			MS_TRACE();
+
+			SetTargetBitrate(initialTargetBitrate);
+		}
+
+		void IntervalBudget::SetTargetBitrate(int64_t targetBitrate)
+		{
+			MS_TRACE();
+
+			this->targetBitrate = targetBitrate;
+			// Bits over a second into bytes over the window.
+			this->maxBytesInBudget = (this->targetBitrate * WindowUs) / (8 * 1000000);
+
+			// What the budget held doesn't survive a window it no longer fits in.
+			this->bytesRemaining =
+			  std::clamp(this->bytesRemaining, -this->maxBytesInBudget, this->maxBytesInBudget);
+		}
+
+		void IntervalBudget::IncreaseBudget(int64_t deltaTimeUs)
+		{
+			MS_TRACE();
+
+			// Bits over a second into the bytes that fit in the span given, which is
+			// negative when the span is, so that time running backwards takes budget
+			// away rather than leaving it untouched.
+			const int64_t bytes = (this->targetBitrate * deltaTimeUs) / (8 * 1000000);
+
+			if (this->bytesRemaining < 0 || this->canBuildUpUnderuse)
+			{
+				// The budget was overspent, so this span makes up for it.
+				this->bytesRemaining = std::min(this->bytesRemaining + bytes, this->maxBytesInBudget);
+			}
+			else
+			{
+				// What was left unspent is not available anymore.
+				this->bytesRemaining = std::min(bytes, this->maxBytesInBudget);
+			}
+		}
+
+		void IntervalBudget::UseBudget(int64_t bytes)
+		{
+			MS_TRACE();
+
+			this->bytesRemaining = std::max(this->bytesRemaining - bytes, -this->maxBytesInBudget);
+		}
+
+		int64_t IntervalBudget::GetBytesRemaining() const
+		{
+			MS_TRACE();
+
+			return std::max<int64_t>(0, this->bytesRemaining);
+		}
+
+		double IntervalBudget::GetBudgetRatio() const
+		{
+			MS_TRACE();
+
+			// Nothing can be left over nor owed at no bitrate at all.
+			if (this->maxBytesInBudget == 0)
+			{
+				return 0.0;
+			}
+
+			return static_cast<double>(this->bytesRemaining) / static_cast<double>(this->maxBytesInBudget);
+		}
+	} // namespace BWE
+} // namespace RTC