@unboundcx/video-sdk-client 2.0.9 → 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/package.json

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