mediasoup 3.27.1 → 3.28.0

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 };
 			};

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

@@ -2,6 +2,7 @@
 #define MS_RTC_BWE_SEND_PACKET_HISTORY_HPP
 
 #include "common.hpp"
+#include "Utils/UnwrappedSequenceNumber.hpp"
 #include "RTC/BWE/BweTypes.hpp"
 #include <map>
 #include <tuple>
@@ -37,14 +38,113 @@ namespace RTC
 				int64_t windowDurationUs{ 60 * 1000 * 1000 };
 			};
 
-		private:
+			/**
+			 * Everything about a packet that this history has to be told, since none
+			 * of it can be read back from the bytes that go on the wire.
+			 */
+			struct AddPacketOptions
+			{
+				uint32_t ssrc{ 0 };
+				/**
+				 * RTP sequence number of the packet, which is what a feedback that
+				 * doesn't carry the one above identifies it by.
+				 */
+				uint16_t seq{ 0 };
+				/**
+				 * Size of the packet including the overhead up to the IP layer (bytes).
+				 *
+				 * @remarks
+				 * - What the link has to carry is what the estimation is about, so the
+				 *   length of the packet on its own falls short. The overhead of the
+				 *   path it takes is what `RTC::TransportTuple::GetPacketOverhead()`
+				 *   answers.
+				 */
+				size_t size{ 0 };
+				/**
+				 * Whether it's an audio packet. False for video, padding and RTX.
+				 */
+				bool isAudio{ false };
+				bool isRetransmission{ false };
+				/**
+				 * SSRC of the packet a retransmission carries, which is the SSRC above
+				 * itself when it goes without RTX. No value when the packet isn't a
+				 * retransmission.
+				 */
+				std::optional<uint32_t> originalSsrc;
+				/**
+				 * Whether the packet is marked as ECT(1), which asks the network to
+				 * report congestion instead of dropping the packet.
+				 *
+				 * @see https://www.rfc-editor.org/rfc/rfc9331.html
+				 */
+				bool sentWithEct1{ false };
+				/**
+				 * The burst the packet belongs to, or no value if it isn't part of one.
+				 */
+				std::optional<Types::ProbeCluster> probeCluster;
+				/**
+				 * Time at which the packet is taken note of, which is not yet the time
+				 * at which it was sent.
+				 */
+				int64_t createdAtUs{ 0 };
+			};
+
+			/**
+			 * A packet as this history holds it, which is what it was sent with plus
+			 * what identifies it on the wire.
+			 */
 			struct SentPacketEntry
 			{
 				Types::SentPacket sentPacket;
+				/**
+				 * Time at which the packet was taken note of, which is what makes it
+				 * fall out of the window. It comes before the packet was sent, and by
+				 * an unbounded amount when the socket cannot take the datagram right
+				 * away.
+				 */
+				int64_t createdAtUs{ 0 };
 				uint32_t ssrc{ 0 };
 				uint16_t seq{ 0 };
+				bool isRetransmission{ false };
+				/**
+				 * Whether what a feedback reports as the arrival time of this packet
+				 * cannot be told from that of another one, which happens when the very
+				 * same SSRC and RTP sequence number were sent more than once.
+				 *
+				 * @remark
+				 * - Nothing in this estimator reads it. It is only of use to SCReAM,
+				 *   another way of estimating the bandwidth, which discards the delay
+				 *   of a packet it cannot tell apart.
+				 *
+				 * @link https://datatracker.ietf.org/doc/draft-johansson-ccwg-rfc8298bis-screamv2
+				 */
+				bool ambiguousReceiveTime{ false };
+				/**
+				 * Whether the packet was sent marked as ECT(1), which asks the network
+				 * to report congestion instead of dropping the packet.
+				 *
+				 * @remark
+				 * - Only a feedback that reports ECN carries it back, which is the one
+				 *   of RFC 8888 and not the transport-cc one.
+				 *
+				 * @see https://datatracker.ietf.org/doc/html/rfc8888
+				 * @see https://www.rfc-editor.org/rfc/rfc9331.html
+				 */
+				bool sentWithEct1{ false };
+				/**
+				 * Whether a feedback already reported this packet as lost, which is
+				 * what tells a first loss from the same loss reported again.
+				 *
+				 * @remark
+				 * - Only a feedback that reports on a whole range of packets makes use
+				 *   of it, which is the one of RFC 8888 and not the transport-cc one.
+				 *
+				 * @see https://datatracker.ietf.org/doc/html/rfc8888
+				 */
+				bool previouslyReportedLost{ false };
 			};
 
+		private:
 			struct SsrcAndSeq
 			{
 				bool operator<(const SsrcAndSeq& other) const
@@ -62,23 +162,58 @@ namespace RTC
 			explicit SendPacketHistory(SendPacketHistoryOptions options);
 
 			/**
-			 * Take note of a packet that has just been sent.
+			 * Take note of a packet that is about to be sent.
+			 *
+			 * @returns The sequence number given to the packet, whose lowest 16 bits
+			 *   are what has to go into the transport-wide sequence number RTP header
+			 *   extension, and which is what a feedback resolves into.
+			 */
+			int64_t AddPacket(const AddPacketOptions& options);
+
+			/**
+			 * Recover the sequence number this history gave a packet out of the
+			 * lowest 16 bits of it that the wire carries.
+			 *
+			 * @remarks
+			 * - Each number is resolved against the previous one resolved, be it of a
+			 *   packet taken note of or of another feedback, which is what carries the
+			 *   count across a turn of the wire's 16 bits. So one further than half
+			 *   that range away from the previous cannot be told apart from the same
+			 *   number a turn later.
+			 */
+			int64_t UnwrapSequenceNumber(uint16_t wrappedSequenceNumber);
+
+			/**
+			 * Take note that the packet with the given sequence number has left.
 			 *
-			 * @param size - Size of the packet including overhead up to the IP layer
-			 *   (bytes).
-			 * @param audio - Whether it's an audio packet. False for video, padding
-			 *   and RTX.
-			 * @returns The sequence number given to the packet, which is what a
-			 *   feedback has to be resolved into.
+			 * @returns The packet as it was sent, or no value if this history doesn't
+			 *   hold it anymore or it had already left.
+			 *
+			 * @remarks
+			 * - This is what makes the packet count as in flight, and what settles how
+			 *   many bytes were in flight when it left.
+			 * - A packet sent under a sequence number that already left is not taken
+			 *   note of twice, so that its bytes are not counted twice either.
+			 */
+			std::optional<Types::SentPacket> ProcessSentPacket(int64_t sequenceNumber, int64_t sentAtUs);
+
+			/**
+			 * Take note of bytes that left without being tracked one by one, which is
+			 * what packets carrying no sequence number of this history amount to.
+			 *
+			 * @remarks
+			 * - They are held until the next tracked packet leaves and are attributed
+			 *   to it, so that whoever measures the acknowledged bitrate doesn't
+			 *   believe the link carried less than it did.
 			 */
-			int64_t AddPacket(uint32_t ssrc, uint16_t seq, size_t size, bool audio, int64_t sentAtUs);
+			void ProcessSentUntrackedPacket(size_t size, int64_t sentAtUs);
 
 			/**
 			 * Resolve what a feedback reported about a single packet.
 			 *
 			 * @param received - Whether the feedback reported the packet as received.
-			 * @returns The packet as it was sent, or no value if this history doesn't
-			 *   hold it anymore.
+			 * @returns The packet as this history holds it, or no value if it doesn't
+			 *   hold it anymore or it was never reported as sent.
 			 *
 			 * @remarks
 			 * - Every packet up to the given one stops counting as in flight, since
@@ -86,24 +221,13 @@ namespace RTC
 			 * - A packet reported as received is dropped, while one reported as lost
 			 *   is kept, since a later feedback may still report it as received.
 			 */
-			std::optional<Types::SentPacket> RetrievePacket(int64_t sequenceNumber, bool received);
+			std::optional<SentPacketEntry> RetrievePacket(int64_t sequenceNumber, bool received);
 
 			/**
 			 * Same, for a feedback that identifies the packet by its SSRC and RTP
 			 * sequence number rather than by the sequence number given to it.
 			 */
-			std::optional<Types::SentPacket> RetrievePacket(uint32_t ssrc, uint16_t seq, bool received);
-
-			/**
-			 * Sequence number this history gave to the latest packet added, or no
-			 * value if no packet was ever added.
-			 *
-			 * @remarks
-			 * - It's the sequence number of this history, not the RTP one, so it
-			 *   never wraps around. It's also the highest a feedback carrying only
-			 *   the lowest bits of it can possibly stand for.
-			 */
-			std::optional<int64_t> GetLastSequenceNumber() const;
+			std::optional<SentPacketEntry> RetrievePacket(uint32_t ssrc, uint16_t seq, bool received);
 
 			/**
 			 * Bytes that were sent and no feedback has reported on yet.
@@ -126,10 +250,22 @@ namespace RTC
 			const SendPacketHistoryOptions options;
 			std::map<int64_t, SentPacketEntry> history;
 			std::map<SsrcAndSeq, int64_t> ssrcAndSeqToSequenceNumber;
-			int64_t nextSequenceNumber{ 0 };
+			// Hands out the sequence numbers and recovers them out of the lowest bits
+			// the wire carries, which keeps both to a single count.
+			Utils::UnwrappedSequenceNumber<uint16_t>::Unwrapper sequenceNumberUnwrapper;
+			uint16_t nextWrappedSequenceNumber{ 0 };
+			// Highest sequence number ever taken note of, or no value if none was.
+			std::optional<int64_t> highestSequenceNumber;
 			// Sequence numbers are never negative, so this sits below all of them.
 			int64_t lastAckSequenceNumber{ -1 };
 			size_t outstandingBytes{ 0 };
+			// Bytes that left untracked and no packet has been attributed yet.
+			size_t pendingUntrackedBytes{ 0 };
+			// Time at which the latest tracked packet left, or no value if none has.
+			std::optional<int64_t> lastSendTimeUs;
+			// Time at which the latest untracked bytes left, or no value if none
+			// have.
+			std::optional<int64_t> lastUntrackedSendTimeUs;
 		};
 	} // namespace BWE
 } // namespace RTC