mediasoup 3.27.0 → 3.28.0

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

@@ -0,0 +1,140 @@
+#define MS_CLASS "RTC::BWE::ProbePacketGenerator"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/ProbePacketGenerator.hpp"
+#include "Logger.hpp"
+#include "RTC/Consts.hpp"
+#include "RTC/RtpDictionaries.hpp"
+#include "Utils.hpp"
+#include <cstring> // std::memcpy()
+#include <vector>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Static. */
+
+		static constexpr size_t ExtensionsBufferLength{ 200 };
+		alignas(4) static thread_local uint8_t ExtensionsBuffer[ExtensionsBufferLength];
+		// How much the RTP timestamp moves from one packet to the next.
+		// NOTE: It stands for no lapse of media, since there is none to play out.
+		// It just has to move so that the packets don't all claim to belong to the
+		// same instant.
+		static constexpr uint32_t TimestampStep{ 20 };
+
+		/* Instance methods. */
+
+		ProbePacketGenerator::ProbePacketGenerator(Listener* listener) : listener(listener)
+		{
+			MS_TRACE();
+
+			this->packet.reset(
+			  RTC::RTP::Packet::Factory(this->packetBuffer.data(), this->packetBuffer.size()));
+
+			this->packet->SetPayloadType(RTC::Consts::BweProbeRtpPayloadType);
+			this->packet->SetSsrc(RTC::Consts::BweProbeRtpSsrc);
+			this->packet->SetSequenceNumber(Utils::Crypto::GetRandomUInt<uint16_t>(0, 65535));
+			this->packet->SetTimestamp(Utils::Crypto::GetRandomUInt<uint32_t>(0, 4294967295));
+
+			// The extensions that make the packets reportable, so that the receiver
+			// tells when each of them arrived.
+			std::vector<RTC::RTP::Packet::Extension> extensions;
+			uint8_t extenLen;
+			uint8_t* bufferPtr{ ExtensionsBuffer };
+
+			// urn:ietf:params:rtp-hdrext:sdes:mid.
+			{
+				extenLen = RTC::Consts::BweProbeRtpMid.size();
+
+				extensions.emplace_back(
+				  /*type*/ RTC::RtpHeaderExtensionUri::Type::MID,
+				  /*id*/ static_cast<uint8_t>(RTC::RtpHeaderExtensionUri::Type::MID),
+				  /*len*/ extenLen,
+				  /*value*/ bufferPtr);
+
+				std::memcpy(bufferPtr, RTC::Consts::BweProbeRtpMid.data(), extenLen);
+
+				bufferPtr += extenLen;
+			}
+
+			// http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time.
+			//
+			// NOTE: Just the id and the room for its value, which whoever sends the
+			// packet fills in.
+			{
+				extenLen = 3;
+
+				extensions.emplace_back(
+				  /*type*/ RTC::RtpHeaderExtensionUri::Type::ABS_SEND_TIME,
+				  /*id*/ static_cast<uint8_t>(RTC::RtpHeaderExtensionUri::Type::ABS_SEND_TIME),
+				  /*len*/ extenLen,
+				  /*value*/ bufferPtr);
+
+				bufferPtr += extenLen;
+			}
+
+			// http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01.
+			//
+			// NOTE: The same, and it's the one the arrival times come back in.
+			{
+				extenLen = 2;
+
+				extensions.emplace_back(
+				  /*type*/ RTC::RtpHeaderExtensionUri::Type::TRANSPORT_WIDE_CC_01,
+				  /*id*/ static_cast<uint8_t>(RTC::RtpHeaderExtensionUri::Type::TRANSPORT_WIDE_CC_01),
+				  /*len*/ extenLen,
+				  /*value*/ bufferPtr);
+			}
+
+			this->packet->SetExtensions(RTC::RTP::Packet::ExtensionsType::OneByte, extensions);
+
+			this->minPacketLength = this->packet->GetLength();
+		}
+
+		void ProbePacketGenerator::GeneratePackets(size_t size)
+		{
+			MS_TRACE();
+
+			if (size > ProbePacketGenerator::MaxGeneratePacketsSize)
+			{
+				MS_WARN_TAG(
+				  bwe,
+				  "burst of more bytes than any real one could be, sending fewer [asked:%zu, sending:%zu]",
+				  size,
+				  ProbePacketGenerator::MaxGeneratePacketsSize);
+
+				size = ProbePacketGenerator::MaxGeneratePacketsSize;
+			}
+
+			size_t remaining{ size };
+
+			while (remaining > 0)
+			{
+				// A packet cannot be shorter than its own header, so the last one of a
+				// burst overshoots rather than falling short.
+				size_t length = std::clamp(
+				  Utils::Byte::PadTo4Bytes(remaining),
+				  this->minPacketLength,
+				  ProbePacketGenerator::MaxPacketLength);
+
+				this->packet->SetSequenceNumber(this->packet->GetSequenceNumber() + 1);
+				this->packet->SetTimestamp(this->packet->GetTimestamp() + TimestampStep);
+				this->packet->SetPayloadLength(length - this->minPacketLength);
+
+				// NOTE: The length is read back rather than assumed, since padding the
+				// payload to 4 bytes may have made the packet longer than asked for.
+				length = this->packet->GetLength();
+
+				remaining -= std::min(remaining, length);
+
+				if (!this->listener->OnProbePacketGeneratorSendRtpPacket(this, this->packet.get()))
+				{
+					MS_DEBUG_DEV("burst given up on, %zu bytes were left", remaining);
+
+					break;
+				}
+			}
+		}
+	} // namespace BWE
+} // namespace RTC

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

@@ -0,0 +1,196 @@
+#define MS_CLASS "RTC::BWE::ProbingScheduler"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/ProbingScheduler.hpp"
+#include "Logger.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Static. */
+
+		// How long before it is due a shot may go out. The instants of a burst are
+		// microseconds apart while the timer only counts milliseconds, so without
+		// this every shot would leave slightly late and the whole burst would
+		// measure a bitrate below the one it was asked for.
+		static constexpr int64_t MaxEarlyProbeProcessingUs{ 1000 };
+
+		/* Instance methods. */
+
+		ProbingScheduler::ScopedShot::ScopedShot(
+		  ProbingScheduler& probingScheduler, const Types::ProbeCluster& probeCluster)
+		  : probingScheduler(probingScheduler)
+		{
+			MS_TRACE();
+
+			this->probingScheduler.shotProbeCluster = probeCluster;
+			this->probingScheduler.shotSentBytes    = 0;
+		}
+
+		ProbingScheduler::ScopedShot::~ScopedShot()
+		{
+			MS_TRACE();
+
+			this->probingScheduler.shotProbeCluster = {};
+			this->probingScheduler.shotSentBytes    = 0;
+		}
+
+		ProbingScheduler::ProbingScheduler(Listener* listener, SharedInterface* shared)
+		  : listener(listener),
+		    shared(shared),
+		    // A burst is made of packets this fabricates, so there is no traffic of
+		    // somebody else's to wait for before one may begin.
+		    bitrateProber(BitrateProber::BitrateProberOptions{ .allowStartProbingImmediately = true }),
+		    probePacketGenerator(this),
+		    nextProbeTimer(shared->CreateTimer(this, "probing-scheduler-next-probe"))
+		{
+			MS_TRACE();
+		}
+
+		void ProbingScheduler::CreateProbeClusters(const std::vector<Types::ProbeClusterConfig>& clusterConfigs)
+		{
+			MS_TRACE();
+
+			for (const auto& clusterConfig : clusterConfigs)
+			{
+				this->bitrateProber.CreateProbeCluster(clusterConfig);
+			}
+
+			// They are scheduled as soon as they are asked for, but not in the stack
+			// of whoever asked: the next turn of the loop picks them up. Emitting from
+			// here would put the send path inside a call that may itself come from the
+			// send path.
+			this->nextProbeTimer->Restart(0);
+		}
+
+		bool ProbingScheduler::OnProbePacketGeneratorSendRtpPacket(
+		  ProbePacketGenerator* /*probePacketGenerator*/, RTC::RTP::Packet* packet)
+		{
+			MS_TRACE();
+
+			if (!this->listener->OnProbingSchedulerSendRtpPacket(this, packet, this->shotProbeCluster))
+			{
+				return false;
+			}
+
+			// What the burst is measured against is what the link has to carry, which
+			// is more than what the packet itself is worth.
+			this->shotSentBytes += packet->GetLength() + this->packetOverhead;
+
+			return true;
+		}
+
+		void ProbingScheduler::OnTimer(TimerHandleInterface* timer)
+		{
+			MS_TRACE();
+
+			if (timer == this->nextProbeTimer.get())
+			{
+				Process();
+			}
+		}
+
+		void ProbingScheduler::Process()
+		{
+			MS_TRACE();
+
+			// Every shot that is already due goes out before giving the loop back,
+			// since one left for the next turn is a shot emitted late and a burst
+			// stretched below the bitrate it was asked for. It always ends: a shot
+			// that goes out pushes the next one forward by the time its bytes take
+			// at the burst's bitrate, which outruns the clock straight away.
+			while (true)
+			{
+				const int64_t nowUs = this->shared->GetTimeUs();
+
+				// NOTE: This may give up on a burst that is due too far in the past, so
+				// it's what decides whether there is anything to emit at all.
+				const auto currentCluster = this->bitrateProber.GetCurrentCluster(nowUs);
+
+				if (!currentCluster.has_value())
+				{
+					ScheduleNextProbe(std::nullopt, nowUs);
+
+					return;
+				}
+
+				const int64_t nextProbeTimeUs = this->bitrateProber.GetNextProbeTimeUs(nowUs).value_or(nowUs);
+
+				// A shot that is almost due goes out now rather than waiting for
+				// another tick of a timer that cannot count in microseconds.
+				if (nowUs + MaxEarlyProbeProcessingUs < nextProbeTimeUs)
+				{
+					ScheduleNextProbe(nextProbeTimeUs, nowUs);
+
+					return;
+				}
+
+				const ScopedShot shot(*this, currentCluster.value().probeCluster);
+
+				const size_t recommendedSize = this->bitrateProber.GetRecommendedMinProbeSize();
+
+				// A burst whose bitrate doesn't amount to a single byte over the time
+				// between two of its shots cannot be emitted at all.
+				if (recommendedSize == 0)
+				{
+					MS_DEBUG_DEV("the burst carries no bytes between shots, giving up on it");
+
+					ScheduleNextProbe(std::nullopt, nowUs);
+
+					return;
+				}
+
+				// The burst opens with the smallest packet there is. What measures it
+				// leaves out the size of the first packet to arrive, so a big one there
+				// throws away much of what the burst carried.
+				if (currentCluster.value().sentBytes == 0)
+				{
+					this->probePacketGenerator.GeneratePackets(this->probePacketGenerator.GetMinPacketLength());
+				}
+
+				if (this->shotSentBytes < recommendedSize)
+				{
+					this->probePacketGenerator.GeneratePackets(recommendedSize - this->shotSentBytes);
+				}
+
+				// Nothing went out, so there is nothing to report and no reason to
+				// believe that trying again would do any better. A burst asked for
+				// later starts everything over.
+				if (this->shotSentBytes == 0)
+				{
+					MS_DEBUG_DEV("no packet of the burst could be sent, giving up on it");
+
+					ScheduleNextProbe(std::nullopt, nowUs);
+
+					return;
+				}
+
+				// NOTE: Reported once for the whole shot rather than per packet, since
+				// this is also what counts the shots a burst is made of. The clock is
+				// read again because handing the packets over took time of its own, and
+				// this instant is what the rest of the burst is measured from.
+				this->bitrateProber.ProbeSent(this->shared->GetTimeUs(), this->shotSentBytes);
+			}
+		}
+
+		void ProbingScheduler::ScheduleNextProbe(std::optional<int64_t> nextProbeTimeUs, int64_t nowUs)
+		{
+			MS_TRACE();
+
+			if (!nextProbeTimeUs.has_value())
+			{
+				this->nextProbeTimer->Stop();
+
+				return;
+			}
+
+			// Truncated rather than rounded up, so that the tick lands just before
+			// the shot is due instead of just after. What is left of the wait by then
+			// is under a millisecond, which is what the margin above is for.
+			const auto timeoutMs = std::max<int64_t>(nextProbeTimeUs.value() - nowUs, 0) / 1000;
+
+			this->nextProbeTimer->Restart(timeoutMs);
+		}
+	} // namespace BWE
+} // namespace RTC

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

@@ -0,0 +1,169 @@
+#define MS_CLASS "RTC::BWE::RembGenerator"
+// #define MS_LOG_DEV_LEVEL 3
+
+#include "RTC/BWE/RembGenerator.hpp"
+#include "Logger.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/* Static. */
+
+		// How often a REMB may be sent when the estimation only goes up or barely
+		// moves.
+		static constexpr int64_t RembSendIntervalMs{ 200 };
+		// How much lower than the latest one an estimation has to be for its REMB to
+		// go out without waiting, as a percentage.
+		static constexpr int64_t SendThresholdPercent{ 103 };
+		// How long the cap may go without being stated, either by a REMB of its own
+		// or by one carrying an estimation that already honours it.
+		static constexpr int64_t LimitationRembIntervalMs{ 1500 };
+		// How many REMBs are sent to announce that the cap is gone, since losing the
+		// only one would leave the remote sender limited forever.
+		static constexpr uint8_t UnlimitedRembNumPackets{ 4 };
+
+		/* Instance methods. */
+
+		RembGenerator::RembGenerator(Listener* listener) : listener(listener)
+		{
+			MS_TRACE();
+		}
+
+		void RembGenerator::OnReceiveBitrateChanged(
+		  int64_t nowMs, const std::vector<uint32_t>& ssrcs, int64_t bitrate)
+		{
+			MS_TRACE();
+
+			if (
+			  this->lastSentRembBitrate.has_value() && this->lastRembSentAtMs.has_value() &&
+			  (bitrate * SendThresholdPercent) / 100 > this->lastSentRembBitrate.value() &&
+			  nowMs - this->lastRembSentAtMs.value() < RembSendIntervalMs)
+			{
+				return;
+			}
+
+			this->lastRembSentAtMs    = nowMs;
+			this->lastSentRembBitrate = bitrate;
+
+			if (this->maxIncomingBitrate.has_value())
+			{
+				bitrate = std::min(bitrate, this->maxIncomingBitrate.value());
+			}
+
+			SendRemb(bitrate, ssrcs);
+		}
+
+		void RembGenerator::SetMaxIncomingBitrate(int64_t nowMs, std::optional<int64_t> bitrate)
+		{
+			MS_TRACE();
+
+			// A cap of zero cannot be told apart from no cap at all, since that is what
+			// a REMB of zero means on the wire, and a negative one means nothing. Both
+			// leave the cap as it was rather than turning into its opposite.
+			if (bitrate.has_value() && bitrate.value() <= 0)
+			{
+				MS_WARN_TAG(
+				  bwe, "ignoring invalid max incoming bitrate [bitrate:%" PRIi64 "]", bitrate.value());
+
+				return;
+			}
+
+			const bool wasLimited = this->maxIncomingBitrate.has_value();
+
+			this->maxIncomingBitrate = bitrate;
+
+			if (!this->maxIncomingBitrate.has_value())
+			{
+				if (wasLimited)
+				{
+					this->unlimitedRembCounter = UnlimitedRembNumPackets;
+
+					MaySendLimitationRembFeedback(nowMs);
+				}
+
+				return;
+			}
+
+			// The cap is back, so the REMBs that were still owed to announce that it
+			// was gone no longer say anything true.
+			this->unlimitedRembCounter = 0;
+
+			// Nothing to tell if a REMB went out recently carrying a bitrate that the
+			// new cap already allows.
+			// NOTE: The instant is taken down either way, since what is already on the
+			// wire honours the cap just as well, and otherwise the next incoming
+			// packet would announce it again right behind that REMB.
+			this->limitationRembSentAtMs = nowMs;
+
+			if (
+			  this->lastRembSentAtMs.has_value() &&
+			  nowMs - this->lastRembSentAtMs.value() < RembSendIntervalMs &&
+			  this->lastSentRembBitrate.has_value() && this->lastSentRembBitrate.value() != 0 &&
+			  this->lastSentRembBitrate.value() <= this->maxIncomingBitrate.value())
+			{
+				return;
+			}
+
+			SendRemb(this->maxIncomingBitrate.value(), {});
+		}
+
+		void RembGenerator::MaySendLimitationRembFeedback(int64_t nowMs)
+		{
+			MS_TRACE();
+
+			const bool announcingRemoval = this->unlimitedRembCounter > 0;
+
+			if (!announcingRemoval && !this->maxIncomingBitrate.has_value())
+			{
+				return;
+			}
+
+			// A REMB carrying the estimation is already no higher than the cap, so
+			// while those keep flowing the cap needs no announcement of its own.
+			if (!announcingRemoval && this->lastRembSentAtMs.has_value() && nowMs - this->lastRembSentAtMs.value() <= LimitationRembIntervalMs)
+			{
+				return;
+			}
+
+			const bool dueAgain = !this->limitationRembSentAtMs.has_value() ||
+			                      nowMs - this->limitationRembSentAtMs.value() > LimitationRembIntervalMs;
+
+			// The first of the REMBs announcing that the cap is gone goes out without
+			// waiting.
+			if (!dueAgain && this->unlimitedRembCounter != UnlimitedRembNumPackets)
+			{
+				return;
+			}
+
+			const int64_t bitrate = this->maxIncomingBitrate.value_or(0);
+
+			MS_DEBUG_DEV("sending limitation REMB [bitrate:%" PRIi64 "]", bitrate);
+
+			this->limitationRembSentAtMs = nowMs;
+
+			if (this->unlimitedRembCounter > 0)
+			{
+				this->unlimitedRembCounter--;
+			}
+
+			SendRemb(bitrate, {});
+		}
+
+		void RembGenerator::SendRemb(int64_t bitrate, const std::vector<uint32_t>& ssrcs)
+		{
+			MS_TRACE();
+
+			RTC::RTCP::FeedbackPsRembPacket packet(uint32_t{ 0 }, uint32_t{ 0 });
+
+			packet.SetBitrate(bitrate);
+
+			if (!ssrcs.empty())
+			{
+				packet.SetSsrcs(ssrcs);
+			}
+
+			this->listener->OnRembGeneratorSendRemb(this, std::addressof(packet));
+		}
+	} // namespace BWE
+} // namespace RTC