@unboundcx/video-sdk-client 2.0.8 → 2.0.10

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,6 +995,8 @@ 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;
+		// Per-layer fraction of the bitrate budget — matches produce().
+		const LAYER_FRACTION = { l: 0.18, m: 0.4, h: 1.0 };
 
 		try {
 			const params = sender.getParameters();
@@ -1000,12 +1013,27 @@ export class LocalMediaManager extends EventEmitter {
 					enc.active = wantActive;
 					changed = true;
 				}
+				if (maxBitrate > 0) {
+					const frac = LAYER_FRACTION[enc.rid] ?? 1.0;
+					const ceiling = Math.round(maxBitrate * frac);
+					const next = Math.min(enc.maxBitrate || ceiling, ceiling);
+					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,32 @@ export class MediasoupManager extends EventEmitter {
             bitrate: "800kbps",
           });
         }
+
+        // HARD bitrate ceiling (data-saver / quality level). The per-branch
+        // numbers above are tuned for full-quality send; on a metered link the
+        // profile's sendMaxBitrate is a budget the encoder must not exceed —
+        // *even during high motion*, which is exactly when resolution/fps caps
+        // alone let the rate spike. Apply it as a ceiling on the top (h) layer,
+        // and scale the lower layers proportionally so the simulcast total
+        // stays within budget. (Screen share never reaches here.)
+        const maxBitrate = Number(options.maxBitrate) || 0;
+        if (maxBitrate > 0 && produceOptions.encodings) {
+          // Fractions of the budget per layer, matching the l/m/h split used
+          // above (~1/8, ~1/3, full). Keys are rids.
+          const LAYER_FRACTION = { l: 0.18, m: 0.4, h: 1.0 };
+          for (const enc of produceOptions.encodings) {
+            const frac = LAYER_FRACTION[enc.rid] ?? 1.0;
+            const ceiling = Math.round(maxBitrate * frac);
+            // Only ever lower — never raise a layer above its tuned value.
+            enc.maxBitrate = Math.min(enc.maxBitrate || ceiling, ceiling);
+          }
+          this.logger.info("VIDEO_QUALITY :: applied hard bitrate ceiling", {
+            maxBitrate: `${(maxBitrate / 1000).toFixed(0)}kbps`,
+            encodings: produceOptions.encodings.map(
+              (e) => `${e.rid}: ${(e.maxBitrate / 1000).toFixed(0)}kbps`,
+            ),
+          });
+        }
         } // end camera-profile else (matches `if (isScreenShare)`)
       }
 

package/managers/StatsCollector.js

@@ -11,6 +11,11 @@ export class StatsCollector {
     this.tracks = new Map(); // trackId -> { participantId, kind }
     this.onStatsCallback = null; // Host-app callback (UI display)
     this._internalCallbacks = []; // SDK-internal subscribers (QualityMonitor)
+    // Previous cumulative byte counts + timestamp per transport, so we can
+    // turn the monotonic bytesSent/bytesReceived counters into an actual
+    // throughput RATE (kbps) instead of a meaningless running total. Keyed by
+    // transportType ('send' | 'recv'). See calculateBandwidth().
+    this._prevBytes = { send: null, recv: null };
   }
 
   /**
@@ -214,37 +219,60 @@ export class StatsCollector {
   }
 
   /**
-   * Calculate bandwidth from stats
+   * Calculate actual throughput from stats.
+   *
+   * bytesSent / bytesReceived are MONOTONIC cumulative counters (total since
+   * the connection started), so summing them yields a meaningless ever-growing
+   * number. To get a real RATE we diff the current total against the previous
+   * sample and divide by the elapsed time. Returns both kbps (for display) and
+   * Mbps (back-compat with existing consumers). The first sample per transport
+   * has no baseline, so its rate is 0 until the next cycle establishes a delta.
+   *
+   * `upload`/`download` (Mbps) are kept for back-compat; `uploadKbps`/
+   * `downloadKbps` are the values the quality panel shows.
    */
   calculateBandwidth(stats, transportType) {
     const bandwidth = {
-      upload: 0,
-      download: 0,
+      upload: 0, // Mbps (back-compat)
+      download: 0, // Mbps (back-compat)
+      uploadKbps: 0,
+      downloadKbps: 0,
       unit: 'Mbps',
     };
 
+    // Sum cumulative bytes across all RTP streams for this transport, and take
+    // the freshest report timestamp as "now" (RTCStats timestamps are in ms).
+    let totalBytes = 0;
+    let ts = 0;
+    const wantType = transportType === 'send' ? 'outbound-rtp' : 'inbound-rtp';
+    const byteField = transportType === 'send' ? 'bytesSent' : 'bytesReceived';
     for (const report of stats.values()) {
+      if (report.type !== wantType) continue;
+      totalBytes += Number(report[byteField]) || 0;
+      if (report.timestamp && report.timestamp > ts) ts = report.timestamp;
+    }
+    if (!ts) ts = Date.now();
+
+    const prev = this._prevBytes[transportType];
+    this._prevBytes[transportType] = { bytes: totalBytes, ts };
+
+    // Need a prior sample to compute a rate. Guard against counter resets
+    // (transport recreated → bytes drop) and non-positive elapsed time.
+    if (prev && totalBytes >= prev.bytes && ts > prev.ts) {
+      const deltaBits = (totalBytes - prev.bytes) * 8;
+      const deltaSec = (ts - prev.ts) / 1000;
+      const bps = deltaBits / deltaSec;
+      const kbps = parseFloat((bps / 1000).toFixed(1));
+      const mbps = parseFloat((bps / 1_000_000).toFixed(2));
       if (transportType === 'send') {
-        if (report.type === 'outbound-rtp') {
-          // Calculate upload bandwidth
-          if (report.bytesSent) {
-            bandwidth.upload += report.bytesSent * 8; // Convert to bits
-          }
-        }
+        bandwidth.uploadKbps = kbps;
+        bandwidth.upload = mbps;
       } else {
-        if (report.type === 'inbound-rtp') {
-          // Calculate download bandwidth
-          if (report.bytesReceived) {
-            bandwidth.download += report.bytesReceived * 8; // Convert to bits
-          }
-        }
+        bandwidth.downloadKbps = kbps;
+        bandwidth.download = mbps;
       }
     }
 
-    // Convert to Mbps
-    bandwidth.upload = parseFloat((bandwidth.upload / 1000000).toFixed(2));
-    bandwidth.download = parseFloat((bandwidth.download / 1000000).toFixed(2));
-
     return bandwidth;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@unboundcx/video-sdk-client",
-	"version": "2.0.8",
+	"version": "2.0.10",
 	"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
   },