mediasoup 3.27.0 → 3.28.0

package/worker/include/RTC/BWE/ProbingScheduler.hpp

@@ -0,0 +1,187 @@
+#ifndef MS_RTC_BWE_PROBING_SCHEDULER_HPP
+#define MS_RTC_BWE_PROBING_SCHEDULER_HPP
+
+#include "common.hpp"
+#include "handles/TimerHandleInterface.hpp"
+#include "RTC/BWE/BitrateProber.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include "RTC/BWE/ProbePacketGenerator.hpp"
+#include "RTC/RTP/Packet.hpp"
+#include "SharedInterface.hpp"
+#include <vector>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Puts a probing burst on the wire at the pace it was asked for.
+		 *
+		 * Somebody else decides that a burst is worth sending and at what bitrate;
+		 * this is what turns that decision into packets leaving at the right
+		 * instants. It holds the burst, asks for the packets that carry the bytes
+		 * due right now, hands them over one by one, and arms a timer for the next
+		 * shot.
+		 *
+		 * The spacing is the whole point. A burst is a bitrate held for a few
+		 * milliseconds, so letting its packets go as fast as the socket takes them
+		 * measures the queue of whoever is in the way instead of the link. The
+		 * instants come from the burst's own start and the bytes gone out so far, so
+		 * a packet that leaves late is made up for by the ones behind it rather than
+		 * dragging the whole burst below the bitrate asked for.
+		 *
+		 * @remarks
+		 * - It is not a pacer. Nothing but the packets of a burst goes through here,
+		 *   media is never queued, and there is no timer running while no burst is
+		 *   being emitted.
+		 */
+		class ProbingScheduler : public ProbePacketGenerator::Listener,
+		                         public TimerHandleInterface::Listener
+		{
+		public:
+			class Listener
+			{
+			public:
+				virtual ~Listener() = default;
+
+			public:
+				/**
+				 * A packet of the burst is ready to go out.
+				 *
+				 * @returns Whether the rest of the burst is still wanted, so that a
+				 * packet that couldn't be sent stops the ones behind it.
+				 *
+				 * @remarks
+				 * - The packet must be sent before returning, since the next one is
+				 *   built over the very same instance.
+				 * - It carries room for the abs-send-time and for the transport wide
+				 *   sequence number but no value for either, so both have to be written
+				 *   here.
+				 * - This must not destroy the `ProbingScheduler`, not even indirectly.
+				 *   It goes on reading its own members after this returns, so
+				 *   returning false is no way out of it either.
+				 */
+				virtual bool OnProbingSchedulerSendRtpPacket(
+				  ProbingScheduler* probingScheduler,
+				  RTC::RTP::Packet* packet,
+				  const Types::ProbeCluster& probeCluster) = 0;
+			};
+
+		private:
+			/**
+			 * Holds what a shot needs while it is being emitted. The packets are
+			 * handed over through a callback, so there is no scope of our own to keep
+			 * it in, and this makes sure it doesn't outlive the shot.
+			 */
+			class ScopedShot
+			{
+			public:
+				ScopedShot(ProbingScheduler& probingScheduler, const Types::ProbeCluster& probeCluster);
+
+				~ScopedShot();
+
+				ScopedShot(const ScopedShot&)            = delete;
+				ScopedShot& operator=(const ScopedShot&) = delete;
+
+			private:
+				ProbingScheduler& probingScheduler;
+			};
+
+		public:
+			ProbingScheduler(Listener* listener, SharedInterface* shared);
+
+			~ProbingScheduler() override = default;
+
+			// NOTE: It hands itself over as the listener of what it owns, so a copy
+			// would leave those pointing at the instance it came from.
+			ProbingScheduler(const ProbingScheduler&)            = delete;
+			ProbingScheduler& operator=(const ProbingScheduler&) = delete;
+
+			/**
+			 * Take the bursts that have been asked for.
+			 *
+			 * @remarks
+			 * - Nothing goes out within this call. The first burst begins on the turn
+			 *   of the event loop that follows, so that the send path never runs
+			 *   inside a call that may itself come from the send path.
+			 * - They are emitted in the order they were asked for, and one asked for
+			 *   long ago is dropped rather than sent late.
+			 */
+			void CreateProbeClusters(const std::vector<Types::ProbeClusterConfig>& clusterConfigs);
+
+			/**
+			 * Bytes that every packet carries on top of its own length once it's on
+			 * the network, so that a burst measures what the link really has to
+			 * carry.
+			 *
+			 * @remarks
+			 * - It depends on the path the packets take, so it has to be set again
+			 *   whenever that changes.
+			 */
+			void SetPacketOverhead(size_t packetOverhead)
+			{
+				this->packetOverhead = packetOverhead;
+			}
+
+			/**
+			 * Whether a burst is being emitted right now.
+			 */
+			bool IsProbing() const
+			{
+				return this->bitrateProber.IsProbing();
+			}
+
+			/* Pure virtual methods inherited from RTC::BWE::ProbePacketGenerator::Listener. */
+		public:
+			bool OnProbePacketGeneratorSendRtpPacket(
+			  ProbePacketGenerator* probePacketGenerator, RTC::RTP::Packet* packet) override;
+
+			/* Pure virtual methods inherited from TimerHandleInterface::Listener. */
+		public:
+			void OnTimer(TimerHandleInterface* timer) override;
+
+		private:
+			/**
+			 * Emit every shot that is due by now and arm the timer for the next one,
+			 * or stop it if there is nothing left to emit.
+			 *
+			 * @remarks
+			 * - More than one may be due when the event loop was held up for longer
+			 *   than the time between two shots. Leaving them for later turns of the
+			 *   loop would stretch the burst and have it measure a bitrate below the
+			 *   one it was asked for.
+			 */
+			void Process();
+
+			/**
+			 * Arm the timer for the given instant, or stop it if there is none.
+			 */
+			void ScheduleNextProbe(std::optional<int64_t> nextProbeTimeUs, int64_t nowUs);
+
+		private:
+			// Passed by argument.
+			Listener* listener{ nullptr };
+			SharedInterface* shared{ nullptr };
+			// Others.
+			// Decides which burst is being emitted and at what instant each of its
+			// packets is due.
+			BitrateProber bitrateProber;
+			// Makes the packets that carry the bytes of a burst.
+			ProbePacketGenerator probePacketGenerator;
+			// Allocated by this.
+			const std::unique_ptr<TimerHandleInterface> nextProbeTimer;
+			// Bytes each packet carries on top of its own length once it's on the
+			// network.
+			size_t packetOverhead{ 0 };
+			// The burst the current shot belongs to, which travels with each of its
+			// packets. Only meaningful while a shot is being emitted, since it's the
+			// generator that calls back and it knows nothing about bursts.
+			Types::ProbeCluster shotProbeCluster;
+			// Bytes of the current shot that have gone out, overhead included, which
+			// is only meaningful while one is being emitted.
+			size_t shotSentBytes{ 0 };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

package/worker/include/RTC/BWE/RembGenerator.hpp

@@ -0,0 +1,96 @@
+#ifndef MS_RTC_BWE_REMB_GENERATOR_HPP
+#define MS_RTC_BWE_REMB_GENERATOR_HPP
+
+#include "common.hpp"
+#include "RTC/RTCP/FeedbackPsRemb.hpp"
+#include <vector>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Tells the remote sender how much it may send towards us, as a REMB.
+		 *
+		 * Two things end up in that single number: what the incoming link is
+		 * estimated to bear, and the cap the application asked for.
+		 */
+		class RembGenerator
+		{
+		public:
+			class Listener
+			{
+			public:
+				virtual ~Listener() = default;
+
+			public:
+				/**
+				 * A REMB packet is ready for the remote sender.
+				 *
+				 * @param packet - Packet to send, only valid for the duration of this
+				 *   call.
+				 */
+				virtual void OnRembGeneratorSendRemb(
+				  RembGenerator* rembGenerator, RTC::RTCP::FeedbackPsRembPacket* packet) = 0;
+			};
+
+		public:
+			explicit RembGenerator(Listener* listener);
+
+			RembGenerator(const RembGenerator&)            = delete;
+			RembGenerator& operator=(const RembGenerator&) = delete;
+
+			/**
+			 * Feed a new estimation of what the incoming link bears (bps).
+			 *
+			 * @param nowMs - Current instant.
+			 * @param ssrcs - Streams the estimation applies to.
+			 *
+			 * @remarks
+			 * - A REMB goes out when the estimation drops enough to be worth telling
+			 *   right away, and otherwise no more often than every 200 ms.
+			 */
+			void OnReceiveBitrateChanged(int64_t nowMs, const std::vector<uint32_t>& ssrcs, int64_t bitrate);
+
+			/**
+			 * Cap what is announced to the remote sender (bps), or no value to
+			 * announce whatever is estimated.
+			 *
+			 * @param nowMs - Current instant.
+			 */
+			void SetMaxIncomingBitrate(int64_t nowMs, std::optional<int64_t> bitrate);
+
+			/**
+			 * Announce the cap again, or that it is gone, which is what gets either
+			 * across when there is no estimation driving anything.
+			 *
+			 * @param nowMs - Current instant.
+			 */
+			void MaySendLimitationRembFeedback(int64_t nowMs);
+
+		private:
+			/**
+			 * Build a REMB carrying the given bitrate and hand it to the listener.
+			 */
+			void SendRemb(int64_t bitrate, const std::vector<uint32_t>& ssrcs);
+
+		private:
+			// Passed by argument.
+			Listener* listener{ nullptr };
+			// Others.
+			// Instant the latest REMB was sent at, or no value until one is.
+			std::optional<int64_t> lastRembSentAtMs;
+			// Bitrate the latest REMB carried, or no value until one is sent. Zero is
+			// a value of its own, since that is how a REMB says there is no limit.
+			std::optional<int64_t> lastSentRembBitrate;
+			// Most that may be announced, or no value when there is no cap.
+			std::optional<int64_t> maxIncomingBitrate;
+			// Instant the cap was last announced at, or no value until it is.
+			std::optional<int64_t> limitationRembSentAtMs;
+			// How many REMBs announcing that the cap is gone are still owed.
+			uint8_t unlimitedRembCounter{ 0 };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

package/worker/include/RTC/BWE/RemoteBitrateEstimatorAbsSendTime.hpp

@@ -0,0 +1,237 @@
+#ifndef MS_RTC_BWE_REMOTE_BITRATE_ESTIMATOR_ABS_SEND_TIME_HPP
+#define MS_RTC_BWE_REMOTE_BITRATE_ESTIMATOR_ABS_SEND_TIME_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/AimdRateControl.hpp"
+#include "RTC/BWE/InterArrival.hpp"
+#include "RTC/BWE/OveruseDetector.hpp"
+#include "RTC/BWE/OveruseEstimator.hpp"
+#include "RTC/RTP/Packet.hpp"
+#include "RTC/RateCalculator.hpp"
+#include <ankerl/unordered_dense.h>
+#include <list>
+#include <vector>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Estimates the bandwidth of the incoming link out of the 'abs-send-time' RTP
+		 * extension, for senders that do not negotiate transport-cc.
+		 *
+		 * There is no feedback to work with here: all the information available is
+		 * the instant each packet says it left the sender and the instant it arrived,
+		 * so the estimation is the delay based detection over the whole group of
+		 * incoming streams. It also detects the bursts a sender emits at the
+		 * beginning of a call and takes their rate as a shortcut to an estimate,
+		 * which is what makes the first seconds of a call usable.
+		 *
+		 * The result travels back to the sender as a REMB, so whoever owns this class
+		 * gets both the estimate and the streams it applies to.
+		 */
+		class RemoteBitrateEstimatorAbsSendTime
+		{
+		public:
+			class Listener
+			{
+			public:
+				virtual ~Listener() = default;
+
+			public:
+				/**
+				 * The estimation of the incoming link changed, so the remote senders of
+				 * the given streams have to be told about it.
+				 *
+				 * @param ssrcs - Streams the estimation applies to, which are those that
+				 *   have sent something recently.
+				 * @param bitrate - Estimated bitrate of the incoming link (bps).
+				 */
+				virtual void OnRemoteBitrateEstimatorAbsSendTimeBitrateChanged(
+				  RemoteBitrateEstimatorAbsSendTime* remoteBitrateEstimator,
+				  const std::vector<uint32_t>& ssrcs,
+				  int64_t bitrate) = 0;
+			};
+
+		private:
+			/**
+			 * A packet that may belong to a burst emitted by the sender.
+			 */
+			struct Probe
+			{
+				/**
+				 * Instant the packet says it left the sender, in the sender's own
+				 * timeline (us).
+				 */
+				int64_t sendTimeUs;
+				/**
+				 * Instant the packet arrived (us).
+				 */
+				int64_t receiveTimeUs;
+				/**
+				 * Size of the packet (bytes).
+				 */
+				size_t payloadSize;
+			};
+
+			/**
+			 * A run of consecutive probes whose send deltas are close enough to each
+			 * other to look like a single burst.
+			 *
+			 * @remarks
+			 * - While a run is being accumulated the fields below hold sums rather than
+			 *   means, and they are divided by `count` when the run is closed.
+			 */
+			struct Cluster
+			{
+				/**
+				 * Rate at which the burst was sent (bps).
+				 */
+				int64_t GetSendBitrate() const
+				{
+					return (static_cast<int64_t>(this->meanSize) * 8 * 1000000) / this->sendMeanUs;
+				}
+
+				/**
+				 * Rate at which the burst was received (bps).
+				 */
+				int64_t GetReceiveBitrate() const
+				{
+					return (static_cast<int64_t>(this->meanSize) * 8 * 1000000) / this->receiveMeanUs;
+				}
+
+				/**
+				 * Mean time between the send instants of two consecutive probes (us).
+				 */
+				int64_t sendMeanUs{ 0 };
+				/**
+				 * Mean time between the arrival instants of two consecutive probes (us).
+				 */
+				int64_t receiveMeanUs{ 0 };
+				/**
+				 * Mean size of the probes (bytes).
+				 */
+				size_t meanSize{ 0 };
+				/**
+				 * Number of probes in the run.
+				 */
+				int count{ 0 };
+				/**
+				 * How many of those probes came far enough apart from the previous one
+				 * for the gap to be measurable.
+				 */
+				int numAboveMinDelta{ 0 };
+			};
+
+			enum class ProbeResult : uint8_t
+			{
+				BITRATE_UPDATED,
+				NO_UPDATE
+			};
+
+		public:
+			explicit RemoteBitrateEstimatorAbsSendTime(Listener* listener);
+
+			RemoteBitrateEstimatorAbsSendTime(const RemoteBitrateEstimatorAbsSendTime&) = delete;
+			RemoteBitrateEstimatorAbsSendTime& operator=(const RemoteBitrateEstimatorAbsSendTime&) = delete;
+
+			/**
+			 * Feed a received RTP packet.
+			 *
+			 * @param packet - Received packet, which is ignored unless it carries the
+			 *   'abs-send-time' extension.
+			 * @param arrivalTimeUs - Instant the packet arrived.
+			 * @param nowUs - Current instant, which is not the one above when packets
+			 *   are processed in batches.
+			 */
+			void IncomingPacket(const RTC::RTP::Packet* packet, int64_t arrivalTimeUs, int64_t nowUs);
+
+			/**
+			 * Feed the round trip time towards the senders, which bounds how often the
+			 * estimation may be reduced.
+			 */
+			void OnRttUpdate(int64_t avgRttUs);
+
+			/**
+			 * Forget a stream, so that it no longer takes part in the estimation nor in
+			 * the streams reported to the listener.
+			 */
+			void RemoveStream(uint32_t ssrc);
+
+			/**
+			 * Latest estimation of the incoming link (bps), or zero while there is
+			 * none or no stream is active.
+			 */
+			int64_t GetLatestEstimate() const;
+
+		private:
+			/**
+			 * Whether the given send delta is close enough to the mean of the run being
+			 * accumulated to belong to it.
+			 */
+			static bool IsWithinClusterBounds(int64_t sendDeltaUs, const Cluster& clusterAggregate);
+
+			/**
+			 * Close the run being accumulated and keep it, unless it is too short or
+			 * covers no time at all.
+			 */
+			static void MaybeAddCluster(const Cluster& clusterAggregate, std::list<Cluster>& clusters);
+
+			/**
+			 * Split the probes seen so far into runs of similar send deltas.
+			 */
+			std::list<Cluster> ComputeClusters() const;
+
+			/**
+			 * The fastest run that looks like a burst that made it through, or none if
+			 * no run does.
+			 */
+			const Cluster* FindBestProbe(const std::list<Cluster>& clusters) const;
+
+			/**
+			 * Look at the probes seen so far and take the rate of the best burst as the
+			 * estimation, if it beats what is already known.
+			 */
+			ProbeResult ProcessClusters(int64_t nowUs);
+
+			/**
+			 * Whether the given rate says something that the current estimation does
+			 * not already say.
+			 */
+			bool IsBitrateImproving(int64_t probeBitrate) const;
+
+			/**
+			 * Forget the streams that have been silent for too long, and start the
+			 * delay based detection over when none is left.
+			 */
+			void TimeoutStreams(int64_t nowUs);
+
+		private:
+			Listener* listener{ nullptr };
+			// Recreated whenever every stream times out, since the groups of a stream
+			// that is gone say nothing about the ones of whatever comes next.
+			std::unique_ptr<InterArrival> interArrival;
+			std::unique_ptr<OveruseEstimator> overuseEstimator;
+			OveruseDetector overuseDetector;
+			// Rate at which data is coming in, which is what bounds the estimation.
+			RTC::RateCalculator incomingRateCalculator;
+			// Whether the meter above has reported a rate at least once, so that a
+			// stream falling silent can be told apart from never having measured
+			// anything.
+			bool incomingBitrateInitialized{ false };
+			// Packets big enough to have been paced by the sender, kept while a burst
+			// is still being looked for.
+			std::list<Probe> probes;
+			// Instant of the first packet ever fed, which bounds how long bursts are
+			// looked for.
+			std::optional<int64_t> firstPacketTimeUs;
+			// Instant the listener was told about the estimation for the last time.
+			std::optional<int64_t> lastUpdateUs;
+			// Instant each stream was last seen at.
+			ankerl::unordered_dense::map<uint32_t, int64_t> ssrcs;
+			AimdRateControl remoteRateControl;
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

package/worker/include/RTC/BWE/RobustThroughputEstimator.hpp

@@ -23,29 +23,54 @@ namespace RTC
 		class RobustThroughputEstimator : public AcknowledgedBitrateEstimatorInterface
 		{
 		public:
+			/**
+			 * @remarks
+			 * - Every constraint documented below is checked by the constructor and
+			 *   aborts when it doesn't hold. These options are set from C++ alone,
+			 *   never from the network nor from the API, so breaking one of them is a
+			 *   programming error.
+			 */
 			struct RobustThroughputEstimatorOptions
 			{
 				/**
 				 * Smallest number of packets the window holds.
+				 *
+				 * @remarks
+				 * - It must be between 10 and 1000.
 				 */
 				size_t windowPackets{ 20 };
 				/**
 				 * Largest number of packets the window holds, so that a high bitrate
 				 * doesn't make it grow without bound.
+				 *
+				 * @remarks
+				 * - It must be between 10 and 1000, and never below `windowPackets`.
 				 */
 				size_t maxWindowPackets{ 500 };
 				/**
 				 * Smallest duration the window covers, so that a low bitrate still gets
 				 * enough packets to measure.
+				 *
+				 * @remarks
+				 * - It must be between 100 and 3000 ms, and never above
+				 *   `maxWindowDurationUs`.
 				 */
 				int64_t minWindowDurationUs{ 1000 * 1000 };
 				/**
 				 * Largest duration the window covers, so that very old packets don't
 				 * weigh on the estimate after sending was paused.
+				 *
+				 * @remarks
+				 * - It must be between 1 and 15 s.
 				 */
 				int64_t maxWindowDurationUs{ 5 * 1000 * 1000 };
 				/**
 				 * Number of packets the window needs before it produces an estimate.
+				 *
+				 * @remarks
+				 * - It must be between 10 and 1000, and never above `windowPackets`,
+				 *   since a window that requires more packets than it holds would reach
+				 *   the sending rate with no send time to compute it from.
 				 */
 				size_t requiredPackets{ 10 };
 				/**
@@ -56,6 +81,7 @@ namespace RTC
 				 * - Set it to 0 when audio is not included in the allocation, and to 1
 				 *   when it is included in the allocation but not in the estimation.
 				 *   Its value is irrelevant once every packet is tracked.
+				 * - It must be between 0 and 1.
 				 */
 				double unackedWeight{ 1.0 };
 			};