Layer suspension (#756)

* Support layer suspension

Add support for a message which notifies the endpoint whether or not it
is selected (meaning its HD stream is in use).  If it is not
selected and enableLayerSuspension is set to true then it will impose a
bandwidth limit in the SDP to suspend sending the higher layers.

* only add the IS_SELECTED_CHANGED listener in JingleSessionPC if layer
suspension is enabled

this prevents doing a local o/a when we don't need it

modules/RTC/BandwidthLimiter.js

@@ -0,0 +1,77 @@
+/* global __filename */
+
+import { getLogger } from 'jitsi-meet-logger';
+import transform from 'sdp-transform';
+
+const logger = getLogger(__filename);
+
+/**
+ * This will save a bandwidth limit (per mline) that should be used
+ * and then, when given an SDP, will enforce that limit.
+ * Note that this will affect *outgoing* bandwidth usage, but the SDP
+ * it must modify to implement that is the *remote* description
+ */
+export default class BandwidthLimiter {
+
+    /**
+     * Create a new BandwidthLimiter
+     */
+    constructor() {
+        /**
+         * @type {Map<String, Number>}
+         * Map of mline media type to a bandwidth limit (in kbps).
+         * Any mlines present in this map will have the associated
+         * bandwidth limit (or 'null' for no limit) enforced, meaning
+         * that it will potentially overwrite a limit already set in
+         * the given sdp.  However, if an mline is NOT present in
+         * this map, any limit in the given sdp will not be touched.
+         */
+        this._bandwidthLimits = new Map();
+    }
+
+    /**
+     * Set a bandwidth limit for given mline.  If limitKbps is null,
+     * the limit will be removed
+     * @param {String} mediaType the mline media type to set the
+     * bandwidth limit on
+     * @param {Number} limitKbps the bandwidth limit, in kbps
+     */
+    setBandwidthLimit(mediaType, limitKbps) {
+        this._bandwidthLimits.set(mediaType, limitKbps);
+    }
+
+    /**
+     * Enforce any configured bandwidth limits (or lack thereof) in the given
+     * sdp
+     * @param {String} sdp the session description
+     * @returns {String} a potentially modified session description
+     * with any configured bandwidth limits set
+     */
+    enforceBandwithLimit(sdp) {
+        logger.debug('Enforcing any configured bandwidth limits');
+        const desc = transform.parse(sdp);
+
+        desc.media.forEach(mLine => {
+            const limitKbps = this._bandwidthLimits.get(mLine.type);
+
+            if (typeof limitKbps !== 'undefined') {
+                if (limitKbps === null) {
+                    logger.debug(
+                        `Removing bandwidth limit for mline ${mLine.type}`);
+                    delete mLine.bandwidth;
+                } else {
+                    logger.debug(`Enforcing limit ${limitKbps}kbps`
+                        + ` for mline ${mLine.type}`);
+                    mLine.bandwidth = [
+                        {
+                            type: 'AS',
+                            limit: limitKbps
+                        }
+                    ];
+                }
+            }
+        });
+
+        return transform.write(desc);
+    }
+}

modules/RTC/BridgeChannel.js

@@ -265,6 +265,13 @@ export default class BridgeChannel {
 
                 break;
             }
+            case 'SelectedUpdateEvent': {
+                const isSelected = obj.isSelected;
+
+                logger.info(`SelectedUpdateEvent isSelected? ${isSelected}`);
+                emitter.emit(RTCEvents.IS_SELECTED_CHANGED, isSelected);
+                break;
+            }
             default: {
                 logger.debug('Channel JSON-formatted message: ', obj);
 

modules/RTC/TraceablePeerConnection.js

@@ -6,6 +6,7 @@ import transform from 'sdp-transform';
 import * as GlobalOnErrorHandler from '../util/GlobalOnErrorHandler';
 import JitsiRemoteTrack from './JitsiRemoteTrack';
 import * as MediaType from '../../service/RTC/MediaType';
+import BandwidthLimiter from './BandwidthLimiter';
 import LocalSdpMunger from './LocalSdpMunger';
 import RTC from './RTC';
 import RTCUtils from './RTCUtils';
@@ -49,6 +50,9 @@ const SIM_LAYER_RIDS = [ SIM_LAYER_1_RID, SIM_LAYER_2_RID, SIM_LAYER_3_RID ];
  *      disabled by removing it from the SDP.
  * @param {boolean} options.preferH264 if set to 'true' H264 will be preferred
  * over other video codecs.
+ * @param {boolean} options.enableLayerSuspension if set to 'true', we will
+ * cap the video send bitrate when we are told we have not been selected by
+ * any endpoints (and therefore the non-thumbnail streams are not in use).
  *
  * FIXME: initially the purpose of TraceablePeerConnection was to be able to
  * debug the peer connection. Since many other responsibilities have been added
@@ -205,6 +209,8 @@ export default function TraceablePeerConnection(
      */
     this.localSdpMunger = new LocalSdpMunger(this);
 
+    this.bandwidthLimiter = new BandwidthLimiter();
+
     /**
      * TracablePeerConnection uses RTC's eventEmitter
      * @type {EventEmitter}
@@ -212,6 +218,12 @@ export default function TraceablePeerConnection(
     this.eventEmitter = rtc.eventEmitter;
     this.rtxModifier = new RtxModifier();
 
+    /**
+     * Whether or not this endpoint has been selected
+     * by a remote participant (via the bridge)
+     */
+    this.isSelected = true;
+
     // override as desired
     this.trace = (what, info) => {
         logger.debug(what, info);
@@ -1043,6 +1055,20 @@ function extractSSRCMap(desc) {
     return ssrcMap;
 }
 
+/**
+ * Get the bitrate cap we should enforce for video given whether or not
+ * we are selected
+ * @param {boolean} isSelected whether or not we (the local endpoint) is
+ * selected by any other endpoints (meaning its HD stream is in use)
+ * @return {Number} the bitrate cap in kbps, or null if there should be
+ * no cap
+ */
+function getSuspensionBitrateKbps(isSelected) {
+    // eslint-disable-next-line max-len
+    // https://codesearch.chromium.org/chromium/src/third_party/webrtc/media/engine/simulcast.cc?l=55&rcl=28deb90728c06a35d8847d2aeda2fc1aee105c5e
+    return isSelected ? null : 200;
+}
+
 /**
  * Takes a SessionDescription object and returns a "normalized" version.
  * Currently it only takes care of ordering the a=ssrc lines.
@@ -1852,6 +1878,21 @@ TraceablePeerConnection.prototype.setRemoteDescription = function(
         });
     }
 
+    if (this.options.enableLayerSuspension) {
+        logger.debug('Layer suspension enabled,'
+            + `currently selected? ${this.isSelected}`);
+        const bitrateCapKbps = getSuspensionBitrateKbps(this.isSelected);
+
+        this.bandwidthLimiter.setBandwidthLimit('video', bitrateCapKbps);
+        logger.debug(`Layer suspension got bitrate cap of ${bitrateCapKbps}`);
+        description.sdp
+            = this.bandwidthLimiter.enforceBandwithLimit(description.sdp);
+        this.trace(
+            'setRemoteDescription::postTransform '
+            + '(layer suspension bitrate cap)',
+            dumpSDP(description));
+    }
+
     // If the browser uses unified plan, transform to it first
     if (browser.usesUnifiedPlan()) {
         // eslint-disable-next-line no-param-reassign
@@ -2486,6 +2527,14 @@ TraceablePeerConnection.prototype.generateNewStreamSSRCInfo = function(track) {
     return ssrcInfo;
 };
 
+/**
+ * Set whether or not the endpoint is 'selected' by other endpoints, meaning
+ * it appears on their main stage
+ */
+TraceablePeerConnection.prototype.setIsSelected = function(isSelected) {
+    this.isSelected = isSelected;
+};
+
 /**
  * Creates a text representation of this <tt>TraceablePeerConnection</tt>
  * instance.

modules/xmpp/JingleSessionPC.js

@@ -17,6 +17,7 @@ import SDPUtil from './SDPUtil';
 import SignalingLayerImpl from './SignalingLayerImpl';
 
 import browser from '../browser';
+import RTCEvents from '../../service/RTC/RTCEvents';
 import Statistics from '../statistics/statistics';
 import XMPPEvents from '../../service/xmpp/XMPPEvents';
 import GlobalOnErrorHandler from '../util/GlobalOnErrorHandler';
@@ -282,6 +283,8 @@ export default class JingleSessionPC extends JingleSession {
             pcOptions.enableFirefoxSimulcast
                 = this.room.options.testing
                     && this.room.options.testing.enableFirefoxSimulcast;
+            pcOptions.enableLayerSuspension
+                = this.room.options.enableLayerSuspension;
         }
 
         this.peerconnection
@@ -477,6 +480,23 @@ export default class JingleSessionPC extends JingleSession {
 
         // The signaling layer will bind it's listeners at this point
         this.signalingLayer.setChatRoom(this.room);
+
+        if (!this.isP2P && this.room.options.enableLayerSuspension) {
+            // If this is the bridge session, we'll listen for
+            // IS_SELECTED_CHANGED events and notify the peer connection
+            this.rtc.addListener(RTCEvents.IS_SELECTED_CHANGED,
+                isSelected => {
+                    this.peerconnection.setIsSelected(isSelected);
+                    logger.info('Doing local O/A due to '
+                        + 'IS_SELECTED_CHANGED event');
+                    this.modificationQueue.push(finishedCallback => {
+                        this._renegotiate()
+                            .then(finishedCallback)
+                            .catch(finishedCallback);
+                    });
+                }
+            );
+        }
     }
 
     /**

service/RTC/RTCEvents.js

@@ -14,6 +14,8 @@ const RTCEvents = {
     DOMINANT_SPEAKER_CHANGED: 'rtc.dominant_speaker_changed',
     LASTN_ENDPOINT_CHANGED: 'rtc.lastn_endpoint_changed',
 
+    IS_SELECTED_CHANGED: 'rtc.is_selected_change',
+
     /**
      * Event emitted when {@link RTC.setLastN} method is called to update with
      * the new value set.