@unboundcx/video-sdk-client 2.0.9 → 2.0.11

package/VideoMeetingClient.js

@@ -791,6 +791,11 @@ export class VideoMeetingClient extends EventEmitter {
       merged.maxResolution = profile.sendResolution;
       merged.frameRate = profile.sendFrameRate;
     }
+    // The hard bitrate ceiling always applies when the profile defines one
+    // (it's the lever that actually protects a metered link on motion).
+    if (profile.sendMaxBitrate) {
+      merged.maxBitrate = profile.sendMaxBitrate;
+    }
     return await this.localMedia.publishCamera(merged);
   }
 

package/managers/LocalMediaManager.js

@@ -276,6 +276,7 @@ export class LocalMediaManager extends EventEmitter {
 				appData: { type: 'video' },
 				simulcast: options.simulcast, // Pass through simulcast option
 				maxResolution: options.maxResolution, // Pass through max resolution preference
+				maxBitrate: options.maxBitrate, // Hard bitrate ceiling (data-saver)
 			});
 
 			this.producers.video = producer;
@@ -880,6 +881,7 @@ export class LocalMediaManager extends EventEmitter {
 	 * @param {Object} profile - from videoQualityProfiles.js
 	 * @param {string|null} profile.sendResolution - '360p'|'540p'|'720p'|'1080p'|null
 	 * @param {number} profile.sendFrameRate
+	 * @param {number|null} profile.sendMaxBitrate - hard ceiling (bps); null = none
 	 * @returns {Promise<void>}
 	 */
 	async setSendQuality(profile = {}) {
@@ -946,8 +948,12 @@ export class LocalMediaManager extends EventEmitter {
 			this.streams.camera = stream;
 			this.rawCameraStream = rawStream;
 
-			// Cap the simulcast top layer to match the new capture resolution.
-			this._capSendSimulcastToResolution(profile.sendResolution);
+			// Cap the simulcast top layer to match the new capture resolution,
+			// and apply the profile's hard bitrate ceiling.
+			this._capSendSimulcastToResolution(
+				profile.sendResolution,
+				profile.sendMaxBitrate || 0
+			);
 
 			this.logger.info('LocalMediaManager :: setSendQuality :: applied', {
 				resolution: `${newTrack.getSettings().width}x${newTrack.getSettings().height}`,
@@ -969,14 +975,19 @@ export class LocalMediaManager extends EventEmitter {
 	}
 
 	/**
-	 * Deactivate simulcast encodings whose source resolution exceeds the cap,
-	 * via RTCRtpSender.setParameters (no renegotiation). null/'1080p' = no cap
-	 * (reactivate everything). Mirrors QualityMonitor's outbound capping but
-	 * keyed off a user-chosen resolution rather than a 'mid'|'low' target.
+	 * Apply the send-side quality cap to the live sender via
+	 * RTCRtpSender.setParameters (no renegotiation). Two things:
+	 *   - deactivate simulcast encodings whose source resolution exceeds the
+	 *     resolution cap (so we don't ship layers above the chosen res), and
+	 *   - apply the HARD bitrate ceiling so the rate can't spike on motion —
+	 *     the same budget produce() applies, mirrored here for the live path.
+	 * null/'1080p' resolution + 0 bitrate = no cap (reactivate everything,
+	 * leave bitrates as-is).
 	 * @private
 	 * @param {string|null} sendResolution
+	 * @param {number} [maxBitrate=0] - hard ceiling (bps); 0 = no bitrate cap
 	 */
-	_capSendSimulcastToResolution(sendResolution) {
+	_capSendSimulcastToResolution(sendResolution, maxBitrate = 0) {
 		const sender = this.producers.video?.rtpSender;
 		if (!sender || typeof sender.getParameters !== 'function') return;
 
@@ -984,16 +995,20 @@ export class LocalMediaManager extends EventEmitter {
 		// Keep a layer active only if its width is within the cap.
 		const capWidth =
 			{ '360p': 640, '540p': 960, '720p': 1280 }[sendResolution] || Infinity;
+		// Relative weights per rid — matches produce(); the budget is split so
+		// the ACTIVE layers SUM to maxBitrate (simulcast total = sum of layers).
+		const WEIGHT = { l: 0.15, m: 0.35, h: 0.65 };
 
 		try {
 			const params = sender.getParameters();
 			if (!params.encodings || params.encodings.length < 2) return;
 			let changed = false;
+			// First pass: decide which layers stay active under the res cap.
+			const settings = this.streams.camera?.getVideoTracks()[0]?.getSettings();
+			const captureWidth = settings?.width || 1920;
 			for (const enc of params.encodings) {
 				// scaleResolutionDownBy tells us this layer's output width
 				// relative to the captured frame; below the cap stays active.
-				const settings = this.streams.camera?.getVideoTracks()[0]?.getSettings();
-				const captureWidth = settings?.width || 1920;
 				const layerWidth = captureWidth / (enc.scaleResolutionDownBy || 1);
 				const wantActive = layerWidth <= capWidth + 1; // +1 for rounding
 				if (enc.active !== wantActive) {
@@ -1001,11 +1016,35 @@ export class LocalMediaManager extends EventEmitter {
 					changed = true;
 				}
 			}
+			// Second pass: split the budget across the layers that remain active,
+			// normalizing weights so the active set sums to the budget.
+			if (maxBitrate > 0) {
+				const active = params.encodings.filter((e) => e.active !== false);
+				const totalWeight = active.reduce(
+					(s, e) => s + (WEIGHT[e.rid] ?? 1.0),
+					0
+				);
+				for (const enc of active) {
+					const w = WEIGHT[enc.rid] ?? 1.0;
+					const share = Math.round((maxBitrate * w) / totalWeight);
+					const next = Math.min(enc.maxBitrate || share, share);
+					if (enc.maxBitrate !== next) {
+						enc.maxBitrate = next;
+						changed = true;
+					}
+				}
+			}
 			if (changed) {
 				sender.setParameters(params);
 				this.logger.info(
 					'LocalMediaManager :: _capSendSimulcastToResolution ::',
-					{ sendResolution, capWidth }
+					{
+						sendResolution,
+						capWidth,
+						maxBitrate: maxBitrate
+							? `${(maxBitrate / 1000).toFixed(0)}kbps`
+							: 'none',
+					}
 				);
 			}
 		} catch (err) {

package/managers/MediasoupManager.js

@@ -673,6 +673,42 @@ export class MediasoupManager extends EventEmitter {
             bitrate: "800kbps",
           });
         }
+
+        // HARD bitrate ceiling (data-saver / quality level). On a metered link
+        // the profile's sendMaxBitrate is a budget the encoder must not exceed
+        // — even during high motion, when resolution/fps caps alone let the
+        // rate spike. With simulcast, total bandwidth is the SUM of all active
+        // layers, so the budget is split across the layers present such that
+        // the layers SUM to the budget (not each capped at the full budget —
+        // that earlier bug let the total reach ~1.6× the cap). The top layer
+        // gets the lion's share; lower layers get proportionally less.
+        // (Screen share never reaches here.)
+        const maxBitrate = Number(options.maxBitrate) || 0;
+        if (maxBitrate > 0 && produceOptions.encodings?.length) {
+          // Relative weights per rid; we normalize over the layers actually
+          // present so the allocated total always equals the budget whether
+          // there are 1, 2, or 3 layers.
+          const WEIGHT = { l: 0.15, m: 0.35, h: 0.65 };
+          const encs = produceOptions.encodings;
+          const totalWeight = encs.reduce(
+            (sum, e) => sum + (WEIGHT[e.rid] ?? 1.0),
+            0,
+          );
+          for (const enc of encs) {
+            const w = WEIGHT[enc.rid] ?? 1.0;
+            const share = Math.round((maxBitrate * w) / totalWeight);
+            // Only ever lower — never raise a layer above its tuned value.
+            enc.maxBitrate = Math.min(enc.maxBitrate || share, share);
+          }
+          const allocated = encs.reduce((s, e) => s + (e.maxBitrate || 0), 0);
+          this.logger.info("VIDEO_QUALITY :: applied hard bitrate ceiling", {
+            budget: `${(maxBitrate / 1000).toFixed(0)}kbps`,
+            allocatedTotal: `${(allocated / 1000).toFixed(0)}kbps`,
+            encodings: encs.map(
+              (e) => `${e.rid}: ${(e.maxBitrate / 1000).toFixed(0)}kbps`,
+            ),
+          });
+        }
         } // end camera-profile else (matches `if (isScreenShare)`)
       }
 

package/managers/StatsCollector.js

@@ -452,15 +452,31 @@ export class StatsCollector {
             report.type === 'outbound-rtp' ||
             report.type === 'remote-outbound-rtp'
           ) {
-            videoStats.packetsSent = this.validateNumber(report.packetsSent);
-            videoStats.bytesSent = this.validateNumber(report.bytesSent);
-            videoStats.framesSent = this.validateNumber(report.framesSent);
-            videoStats.framesPerSecond = this.validateNumber(
-              report.framesPerSecond,
-            );
-            videoStats.frameHeight = this.validateNumber(report.frameHeight);
-            videoStats.frameWidth = this.validateNumber(report.frameWidth);
-            videoStats.scalabilityMode = report.scalabilityMode;
+            // SIMULCAST: there's one outbound-rtp report PER active layer
+            // (l/m/h). Counters that represent the whole producer (bytes,
+            // packets, frames) accumulate across layers; resolution/fps must
+            // reflect the TOP active layer, so only overwrite those when this
+            // report is a bigger frame than what we've seen. Without this the
+            // last report (often the lowest layer) wins and the panel shows
+            // e.g. 270p while we're actually sending 540p.
+            videoStats.packetsSent =
+              (videoStats.packetsSent || 0) +
+              this.validateNumber(report.packetsSent);
+            videoStats.bytesSent =
+              (videoStats.bytesSent || 0) +
+              this.validateNumber(report.bytesSent);
+            videoStats.framesSent =
+              (videoStats.framesSent || 0) +
+              this.validateNumber(report.framesSent);
+            const w = this.validateNumber(report.frameWidth);
+            if (w >= (videoStats.frameWidth || 0)) {
+              videoStats.frameWidth = w;
+              videoStats.frameHeight = this.validateNumber(report.frameHeight);
+              videoStats.framesPerSecond = this.validateNumber(
+                report.framesPerSecond,
+              );
+              videoStats.scalabilityMode = report.scalabilityMode;
+            }
             videoStats.qpSum = report.qpSum;
             videoStats.totalPacketSendDelay = this.validateNumber(
               report.totalPacketSendDelay,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@unboundcx/video-sdk-client",
-	"version": "2.0.9",
+	"version": "2.0.11",
 	"description": "Framework-agnostic WebRTC video meeting SDK powered by mediasoup",
 	"type": "module",
 	"main": "index.js",

package/videoQualityProfiles.js

@@ -10,6 +10,13 @@
 //                             simulcast top layer). null = no cap (use device
 //                             default / 1080p).
 //             sendFrameRate   capture frame-rate cap.
+//             sendMaxBitrate  HARD ceiling (bps) on the top simulcast layer.
+//                             This is the lever that actually protects a
+//                             metered link: resolution/fps are encoder
+//                             *inputs* it tries to honor, but maxBitrate is a
+//                             budget it cannot exceed — even during high
+//                             motion. null = no explicit cap (encoder default
+//                             for the resolution).
 //
 //   receive — the ceiling on what we pull from every remote peer:
 //             maxSpatialLayer   highest simulcast spatial layer we'll accept
@@ -38,6 +45,7 @@ export const VIDEO_QUALITY_PROFILES = Object.freeze({
     label: 'Auto',
     sendResolution: null, // device default (≈1080p)
     sendFrameRate: 30,
+    sendMaxBitrate: null, // no explicit cap
     maxSpatialLayer: null, // no ceiling — tile-size auto-selection wins
     maxTemporalLayer: null,
   },
@@ -48,14 +56,18 @@ export const VIDEO_QUALITY_PROFILES = Object.freeze({
     label: 'High',
     sendResolution: '1080p',
     sendFrameRate: 30,
+    sendMaxBitrate: null, // no explicit cap (encoder default for 1080p)
     maxSpatialLayer: 2,
     maxTemporalLayer: 2,
   },
-  // The "Data saver" target. Meaningful savings, still very usable face video.
+  // The "Data saver" target — tuned for metered cellular / Starlink. 540p at a
+  // slightly reduced frame rate, with a HARD 600kbps send ceiling so motion
+  // can't spike the link. Receive capped at the mid simulcast layer.
   medium: {
     label: 'Medium',
     sendResolution: '540p',
-    sendFrameRate: 30,
+    sendFrameRate: 24,
+    sendMaxBitrate: 600000, // hard ~600kbps ceiling — guaranteed even on motion
     maxSpatialLayer: 1, // never accept the 1080p layer from anyone
     maxTemporalLayer: 2,
   },
@@ -64,6 +76,7 @@ export const VIDEO_QUALITY_PROFILES = Object.freeze({
     label: 'Low',
     sendResolution: '360p',
     sendFrameRate: 15,
+    sendMaxBitrate: 250000, // hard ~250kbps ceiling
     maxSpatialLayer: 0, // lowest layer only
     maxTemporalLayer: 1, // ≈half frame-rate on receive
   },