feat: generates source names (#1725)

This is the first step in adding support for multiple
streams per endpoint. Each source(stream?) needs to have
an identifier. For now always generate the 0 index name
until the machinery for sending more than 1 stream is put
in place.

* send only MSID attribute

* add feature flag for source name signaling

* log a msg if source name signaling is enabled

JitsiMeetJS.js

@@ -21,6 +21,7 @@ import { ParticipantConnectionStatus }
 import getActiveAudioDevice from './modules/detection/ActiveDeviceDetector';
 import * as DetectionEvents from './modules/detection/DetectionEvents';
 import TrackVADEmitter from './modules/detection/TrackVADEmitter';
+import FeatureFlags from './modules/flags/FeatureFlags';
 import ProxyConnectionService
     from './modules/proxyconnection/ProxyConnectionService';
 import recordingConstants from './modules/recording/recordingConstants';
@@ -146,6 +147,11 @@ export default _mergeNamespaceAndModule({
         Settings.init(options.externalStorage);
         Statistics.init(options);
 
+        // Configure the feature flags.
+        FeatureFlags.init({
+            sourceNameSignaling: options.sourceNameSignaling
+        });
+
         // Initialize global window.connectionTimes
         // FIXME do not use 'window'
         if (!window.connectionTimes) {

modules/flags/FeatureFlags.js

@@ -0,0 +1,30 @@
+import { getLogger } from 'jitsi-meet-logger';
+
+const logger = getLogger('FeatureFlags');
+
+/**
+ * A global module for accessing information about different feature flags state.
+ */
+class FeatureFlags {
+    /**
+     * Configures the module.
+     *
+     * @param {boolean} flags.sourceNameSignaling - Enables source names in the signaling.
+     */
+    init(flags) {
+        this._sourceNameSignaling = Boolean(flags.sourceNameSignaling);
+
+        logger.info(`Source name signaling: ${this._sourceNameSignaling}`);
+    }
+
+    /**
+     * Checks if the source name signaling is enabled.
+     *
+     * @returns {boolean}
+     */
+    isSourceNameSignalingEnabled() {
+        return this._sourceNameSignaling;
+    }
+}
+
+export default new FeatureFlags();

modules/sdp/LocalSdpMunger.js

@@ -5,6 +5,7 @@ import { getLogger } from 'jitsi-meet-logger';
 import MediaDirection from '../../service/RTC/MediaDirection';
 import * as MediaType from '../../service/RTC/MediaType';
 import VideoType from '../../service/RTC/VideoType';
+import FeatureFlags from '../flags/FeatureFlags';
 
 import { SdpTransformWrap } from './SdpTransformUtil';
 
@@ -309,12 +310,14 @@ export default class LocalSdpMunger {
 
         if (audioMLine) {
             this._transformMediaIdentifiers(audioMLine);
+            this._injectSourceNames(audioMLine);
         }
 
         const videoMLine = transformer.selectMedia('video');
 
         if (videoMLine) {
             this._transformMediaIdentifiers(videoMLine);
+            this._injectSourceNames(videoMLine);
         }
 
         return new RTCSessionDescription({
@@ -322,4 +325,42 @@ export default class LocalSdpMunger {
             sdp: transformer.toRawSDP()
         });
     }
+
+    /**
+     * Injects source names. Source names are need to for multiple streams per endpoint support. The final plan is to
+     * use the "mid" attribute for source names, but because the SDP to Jingle conversion still operates in the Plan-B
+     * semantics (one source name per media), a custom "name" attribute is injected into SSRC lines..
+     *
+     * @param {MLineWrap} mediaSection - The media part (audio or video) of the session description which will be
+     * modified in place.
+     * @returns {void}
+     * @private
+     */
+    _injectSourceNames(mediaSection) {
+        if (!FeatureFlags.isSourceNameSignalingEnabled()) {
+            return;
+        }
+
+        const sources = [ ...new Set(mediaSection.mLine?.ssrcs?.map(s => s.id)) ];
+        const mediaType = mediaSection.mLine?.type;
+
+        if (!mediaType) {
+            throw new Error('_transformMediaIdentifiers - no media type in mediaSection');
+        }
+
+        for (const source of sources) {
+            const nameExists = mediaSection.ssrcs.find(ssrc => ssrc.id === source && ssrc.attribute === 'name');
+
+            if (!nameExists) {
+                const firstLetterOfMediaType = mediaType.substring(0, 1);
+
+                // Inject source names as a=ssrc:3124985624 name:endpointA-v0
+                mediaSection.ssrcs.push({
+                    id: source,
+                    attribute: 'name',
+                    value: `${this.localEndpointId}-${firstLetterOfMediaType}0`
+                });
+            }
+        }
+    }
 }

modules/sdp/LocalSdpMunger.spec.js

@@ -2,6 +2,7 @@
 import * as transform from 'sdp-transform';
 
 import { MockPeerConnection } from '../RTC/MockClasses';
+import FeatureFlags from '../flags/FeatureFlags';
 
 import LocalSdpMunger from './LocalSdpMunger';
 import { default as SampleSdpStrings } from './SampleSdpStrings.js';
@@ -25,10 +26,10 @@ describe('TransformSdpsForUnifiedPlan', () => {
     const localEndpointId = 'sRdpsdg';
 
     beforeEach(() => {
+        FeatureFlags.init({ });
         localSdpMunger = new LocalSdpMunger(tpc, localEndpointId);
     });
     describe('stripSsrcs', () => {
-        beforeEach(() => { }); // eslint-disable-line no-empty-function
         it('should strip ssrcs from an sdp with no msid', () => {
             localSdpMunger.tpc.isP2P = false;
 
@@ -46,19 +47,35 @@ describe('TransformSdpsForUnifiedPlan', () => {
             expect(videoSsrcs.length).toEqual(0);
         });
 
-        it('should do nothing to an sdp with msid', () => {
-            const sdpStr = transform.write(SampleSdpStrings.simulcastSdp);
-            const desc = new RTCSessionDescription({
-                type: 'offer',
-                sdp: sdpStr
+        describe('should do nothing to an sdp with msid', () => {
+            let audioSsrcs, videoSsrcs;
+
+            const transformStreamIdentifiers = () => {
+                const sdpStr = transform.write(SampleSdpStrings.simulcastSdp);
+                const desc = new RTCSessionDescription({
+                    type: 'offer',
+                    sdp: sdpStr
+                });
+                const transformedDesc = localSdpMunger.transformStreamIdentifiers(desc);
+                const newSdp = transform.parse(transformedDesc.sdp);
+
+                audioSsrcs = getSsrcLines(newSdp, 'audio');
+                videoSsrcs = getSsrcLines(newSdp, 'video');
+            };
+
+            it('without source name signaling enabled (no injected source name)', () => {
+                transformStreamIdentifiers();
+
+                expect(audioSsrcs.length).toEqual(4);
+                expect(videoSsrcs.length).toEqual(6);
             });
-            const transformedDesc = localSdpMunger.transformStreamIdentifiers(desc);
-            const newSdp = transform.parse(transformedDesc.sdp);
-            const audioSsrcs = getSsrcLines(newSdp, 'audio');
-            const videoSsrcs = getSsrcLines(newSdp, 'video');
+            it('with source name signaling enabled (injected source name)', () => {
+                FeatureFlags.init({ sourceNameSignaling: true });
+                transformStreamIdentifiers();
 
-            expect(audioSsrcs.length).toEqual(4);
-            expect(videoSsrcs.length).toEqual(6);
+                expect(audioSsrcs.length).toEqual(4 + 1 /* injected source name */);
+                expect(videoSsrcs.length).toEqual(6 + 3 /* injected source name into each ssrc */);
+            });
         });
     });
 
@@ -108,25 +125,41 @@ describe('DoNotTransformSdpForPlanB', () => {
     const localEndpointId = 'sRdpsdg';
 
     beforeEach(() => {
+        FeatureFlags.init({ });
         localSdpMunger = new LocalSdpMunger(tpc, localEndpointId);
     });
     describe('stripSsrcs', () => {
-        beforeEach(() => { }); // eslint-disable-line no-empty-function
-        it('should not strip ssrcs from an sdp with no msid', () => {
-            localSdpMunger.tpc.isP2P = false;
+        describe('should not strip ssrcs from an sdp with no msid', () => {
+            let audioSsrcs, videoSsrcs;
 
-            const sdpStr = transform.write(SampleSdpStrings.recvOnlySdp);
-            const desc = new RTCSessionDescription({
-                type: 'offer',
-                sdp: sdpStr
+            const transformStreamIdentifiers = () => {
+                localSdpMunger.tpc.isP2P = false;
+
+                const sdpStr = transform.write(SampleSdpStrings.recvOnlySdp);
+                const desc = new RTCSessionDescription({
+                    type: 'offer',
+                    sdp: sdpStr
+                });
+                const transformedDesc = localSdpMunger.transformStreamIdentifiers(desc);
+                const newSdp = transform.parse(transformedDesc.sdp);
+
+                audioSsrcs = getSsrcLines(newSdp, 'audio');
+                videoSsrcs = getSsrcLines(newSdp, 'video');
+            };
+
+            it('without source name signaling', () => {
+                transformStreamIdentifiers();
+
+                expect(audioSsrcs.length).toEqual(1);
+                expect(videoSsrcs.length).toEqual(1);
             });
-            const transformedDesc = localSdpMunger.transformStreamIdentifiers(desc);
-            const newSdp = transform.parse(transformedDesc.sdp);
-            const audioSsrcs = getSsrcLines(newSdp, 'audio');
-            const videoSsrcs = getSsrcLines(newSdp, 'video');
+            it('with source name signaling', () => {
+                FeatureFlags.init({ sourceNameSignaling: true });
+                transformStreamIdentifiers();
 
-            expect(audioSsrcs.length).toEqual(1);
-            expect(videoSsrcs.length).toEqual(1);
+                expect(audioSsrcs.length).toEqual(1 + 1 /* injected source name */);
+                expect(videoSsrcs.length).toEqual(1 + 1 /* injected source name */);
+            });
         });
     });
 });

modules/sdp/SDP.js

@@ -2,6 +2,7 @@
 
 import MediaDirection from '../../service/RTC/MediaDirection';
 import browser from '../browser';
+import FeatureFlags from '../flags/FeatureFlags';
 
 import SDPUtil from './SDPUtil';
 
@@ -203,31 +204,23 @@ SDP.prototype.toJingle = function(elem, thecreator) {
                 const ssrcMap = SDPUtil.parseSSRC(this.media[i]);
 
                 for (const [ availableSsrc, ssrcParameters ] of ssrcMap) {
+                    const sourceName = SDPUtil.parseSourceNameLine(ssrcParameters);
+
                     elem.c('source', {
                         ssrc: availableSsrc,
+                        name: FeatureFlags.isSourceNameSignalingEnabled() ? sourceName : undefined,
                         xmlns: 'urn:xmpp:jingle:apps:rtp:ssma:0'
                     });
 
-                    ssrcParameters.forEach(ssrcSdpLine => {
-                        // get everything after first space
-                        const idx = ssrcSdpLine.indexOf(' ');
-                        const kv = ssrcSdpLine.substr(idx + 1);
+                    const msid = SDPUtil.parseMSIDAttribute(ssrcParameters);
 
+                    // eslint-disable-next-line max-depth
+                    if (msid) {
                         elem.c('parameter');
-                        if (kv.indexOf(':') === -1) {
-                            elem.attrs({ name: kv });
-                        } else {
-                            const name = kv.split(':', 2)[0];
-
-                            elem.attrs({ name });
-
-                            let v = kv.split(':', 2)[1];
-
-                            v = SDPUtil.filterSpecialChars(v);
-                            elem.attrs({ value: v });
-                        }
+                        elem.attrs({ name: 'msid' });
+                        elem.attrs({ value: msid });
                         elem.up();
-                    });
+                    }
 
                     elem.up();
                 }

modules/sdp/SDP.spec.js

@@ -1,6 +1,8 @@
 /* globals $ */
 import { $iq } from 'strophe.js';
 
+import FeatureFlags from '../flags/FeatureFlags';
+
 import SDP from './SDP';
 
 /**
@@ -11,6 +13,9 @@ function createStanzaElement(xml) {
 }
 
 describe('SDP', () => {
+    afterEach(() => {
+        FeatureFlags.init({ });
+    });
     describe('toJingle', () => {
         /* eslint-disable max-len*/
         const testSdp = [
@@ -35,6 +40,7 @@ describe('SDP', () => {
             'a=fingerprint:sha-256 A9:00:CC:F9:81:33:EA:E9:E3:B4:01:E9:9E:18:B3:9B:F8:49:25:A0:5D:12:20:70:D5:6F:34:5A:2A:39:19:0A\r\n',
             'a=ssrc:2002 msid:26D16D51-503A-420B-8274-3DD1174E498F 8205D1FC-50B4-407C-87D5-9C45F1B779F0\r\n',
             'a=ssrc:2002 cname:juejgy8a01\r\n',
+            'a=ssrc:2002 name:a8f7g30-a0\r\n',
             'a=rtcp-mux\r\n',
             'm=video 9 UDP/TLS/RTP/SAVPF 107 100 99 96\r\n',
             'c=IN IP4 0.0.0.0\r\n',
@@ -65,6 +71,8 @@ describe('SDP', () => {
             'a=ssrc:4005 msid:7C0035E5-2DA1-4AEA-804A-9E75BF9B3768 225E9CDA-0384-4C92-92DD-E74C1153EC68\r\n',
             'a=ssrc:4004 cname:juejgy8a01\r\n',
             'a=ssrc:4005 cname:juejgy8a01\r\n',
+            'a=ssrc:4004 name:a8f7g30-v0\r\n',
+            'a=ssrc:4005 name:a8f7g30-v0\r\n',
             'a=ssrc-group:FID 4004 4005\r\n',
             'a=rtcp-mux\r\n'
         ].join('');
@@ -87,19 +95,40 @@ describe('SDP', () => {
             sdp.toJingle(accept, false);
 
             const { nodeTree } = accept;
-            const descriptions
-                = Array.from(nodeTree.getElementsByTagName('description'));
-            const videoDescriptions = descriptions.filter(description =>
-                description.getAttribute('media') === 'video');
-            const count = videoDescriptions.reduce((iterator, description) => {
-                const childNodes = Array.from(description.childNodes);
-                const childNodesSources = childNodes.filter(child =>
-                    child.nodeName === 'source');
-
-                return iterator + childNodesSources.length;
-            }, 0);
-
-            expect(count).toBe(2);
+            const videoSources = nodeTree.querySelectorAll('description[media=\'video\']>source');
+
+            expect(videoSources.length).toBe(2);
+        });
+        it('put source names as source element attributes', () => {
+            FeatureFlags.init({ sourceNameSignaling: true });
+
+            const sdp = new SDP(testSdp);
+            const accept = $iq({
+                to: 'peerjid',
+                type: 'set'
+            })
+                .c('jingle', {
+                    xmlns: 'urn:xmpp:jingle:1',
+                    action: 'session-accept',
+                    initiator: false,
+                    responder: true,
+                    sid: 'temp-sid'
+                });
+
+            sdp.toJingle(accept, false);
+
+            const { nodeTree } = accept;
+
+            const audioSources = nodeTree.querySelectorAll('description[media=\'audio\']>source');
+            const videoSources = nodeTree.querySelectorAll('description[media=\'video\']>source');
+
+            for (const source of audioSources) {
+                expect(source.getAttribute('name')).toBe('a8f7g30-a0');
+            }
+
+            for (const source of videoSources) {
+                expect(source.getAttribute('name')).toBe('a8f7g30-v0');
+            }
         });
     });
 

modules/sdp/SDPDiffer.js

@@ -1,3 +1,5 @@
+import FeatureFlags from '../flags/FeatureFlags';
+
 import SDPUtil from './SDPUtil';
 
 // this could be useful in Array.prototype.
@@ -167,28 +169,25 @@ SDPDiffer.prototype.toJingle = function(modify) {
         // generate sources from lines
         Object.keys(media.ssrcs).forEach(ssrcNum => {
             const mediaSsrc = media.ssrcs[ssrcNum];
+            const ssrcLines = mediaSsrc.lines;
+            const sourceName = SDPUtil.parseSourceNameLine(ssrcLines);
 
             modify.c('source', { xmlns: 'urn:xmpp:jingle:apps:rtp:ssma:0' });
-            modify.attrs({ ssrc: mediaSsrc.ssrc });
+            modify.attrs({
+                name: FeatureFlags.isSourceNameSignalingEnabled() ? sourceName : undefined,
+                ssrc: mediaSsrc.ssrc
+            });
 
-            // iterate over ssrc lines
-            mediaSsrc.lines.forEach(line => {
-                const idx = line.indexOf(' ');
-                const kv = line.substr(idx + 1);
+            // Only MSID attribute is sent
+            const msid = SDPUtil.parseMSIDAttribute(ssrcLines);
 
+            if (msid) {
                 modify.c('parameter');
-                if (kv.indexOf(':') === -1) {
-                    modify.attrs({ name: kv });
-                } else {
-                    const nv = kv.split(':', 2);
-                    const name = nv[0];
-                    const value = SDPUtil.filterSpecialChars(nv[1]);
-
-                    modify.attrs({ name });
-                    modify.attrs({ value });
-                }
-                modify.up(); // end of parameter
-            });
+                modify.attrs({ name: 'msid' });
+                modify.attrs({ value: msid });
+                modify.up();
+            }
+
             modify.up(); // end of source
         });
 

modules/sdp/SDPDiffer.spec.js

@@ -0,0 +1,71 @@
+import { $iq } from 'strophe.js';
+
+import FeatureFlags from '../flags/FeatureFlags';
+
+import SDP from './SDP';
+import SDPDiffer from './SDPDiffer';
+
+describe('SDPDiffer', () => {
+    beforeEach(() => {
+        FeatureFlags.init({ });
+    });
+    describe('toJingle', () => {
+        /* eslint-disable max-len*/
+        const testSdpOld = [
+            'v=0\r\n',
+            'o=thisisadapterortc 2719486166053431 0 IN IP4 127.0.0.1\r\n',
+            's=-\r\n',
+            't=0 0\r\n',
+            'a=group:BUNDLE audio video\r\n',
+            'm=audio 9 UDP/TLS/RTP/SAVPF 111 126\r\n',
+            'a=mid:audio\r\n',
+            'a=ssrc:2002 msid:26D16D51-503A-420B-8274-3DD1174E498F 8205D1FC-50B4-407C-87D5-9C45F1B779F0\r\n',
+            'a=ssrc:2002 cname:juejgy8a01\r\n',
+            'a=ssrc:2002 name:a8f7g30-a0\r\n',
+            'm=video 9 UDP/TLS/RTP/SAVPF 107 100 99 96\r\n',
+            'a=mid:video\r\n'
+        ].join('');
+        const testSdpNew = [
+            'm=audio 9 UDP/TLS/RTP/SAVPF 111 126\r\n',
+            'a=mid:audio\r\n',
+            'm=video 9 UDP/TLS/RTP/SAVPF 107 100 99 96\r\n',
+            'a=mid:video\r\n',
+            'a=ssrc:4004 msid:7C0035E5-2DA1-4AEA-804A-9E75BF9B3768 225E9CDA-0384-4C92-92DD-E74C1153EC68\r\n',
+            'a=ssrc:4005 msid:7C0035E5-2DA1-4AEA-804A-9E75BF9B3768 225E9CDA-0384-4C92-92DD-E74C1153EC68\r\n',
+            'a=ssrc:4004 cname:juejgy8a01\r\n',
+            'a=ssrc:4005 cname:juejgy8a01\r\n',
+            'a=ssrc:4004 name:a8f7g30-v0\r\n',
+            'a=ssrc:4005 name:a8f7g30-v0\r\n',
+            'a=ssrc-group:FID 4004 4005\r\n'
+        ].join('');
+        /* eslint-enable max-len*/
+
+        it('should include source names in added/removed sources', () => {
+            FeatureFlags.init({ sourceNameSignaling: true });
+
+            const newToOldDiff = new SDPDiffer(new SDP(testSdpNew), new SDP(testSdpOld));
+            const sourceRemoveIq = $iq({})
+                .c('jingle', { action: 'source-remove' });
+
+            newToOldDiff.toJingle(sourceRemoveIq);
+
+            const removedAudioSources = sourceRemoveIq.nodeTree
+                .querySelectorAll('description[media=\'audio\']>source');
+
+            expect(removedAudioSources[0].getAttribute('name')).toBe('a8f7g30-a0');
+
+            const oldToNewDiff = new SDPDiffer(new SDP(testSdpOld), new SDP(testSdpNew));
+            const sourceAddIq = $iq({})
+                .c('jingle', { action: 'source-add' });
+
+            oldToNewDiff.toJingle(sourceAddIq);
+
+            const addedVideoSources = sourceAddIq.nodeTree
+                .querySelectorAll('description[media=\'video\']>source');
+
+            expect(addedVideoSources.length).toBe(2);
+            expect(addedVideoSources[0].getAttribute('name')).toBe('a8f7g30-v0');
+            expect(addedVideoSources[1].getAttribute('name')).toBe('a8f7g30-v0');
+        });
+    });
+});

modules/sdp/SDPUtil.js

@@ -46,6 +46,24 @@ const SDPUtil = {
     parseMID(line) {
         return line.substring(6);
     },
+
+    /**
+     * Finds the MSID attribute in the given array of SSRC attribute lines and returns the value.
+     *
+     * @param {string[]} ssrcLines - an array of lines similar to 'a:213123 msid:stream-id track-id'.
+     * @returns {undefined|string}
+     */
+    parseMSIDAttribute(ssrcLines) {
+        const msidLine = ssrcLines.find(line => line.indexOf(' msid:') > 0);
+
+        if (!msidLine) {
+            return undefined;
+        }
+
+        const v = msidLine.substring(msidLine.indexOf(' msid:') + 6 /* the length of ' msid:' */);
+
+        return SDPUtil.filterSpecialChars(v);
+    },
     parseMLine(line) {
         const data = {};
         const parts = line.substring(2).split(' ');
@@ -261,6 +279,19 @@ const SDPUtil = {
 
         return data;
     },
+
+    /**
+     * Gets the source name out of the name attribute "a=ssrc:254321 name:name1".
+     *
+     * @param {string[]} ssrcLines
+     * @returns {string | undefined}
+     */
+    parseSourceNameLine(ssrcLines) {
+        const sourceNameLine = ssrcLines.find(ssrcSdpLine => ssrcSdpLine.indexOf(' name:') > 0);
+
+        // Everything past the "name:" part
+        return sourceNameLine?.substring(sourceNameLine.indexOf(' name:') + 6);
+    },
     parseRTCPFB(line) {
         const parts = line.substr(10).split(' ');
         const data = {};

modules/xmpp/strophe.jingle.js

@@ -10,6 +10,7 @@ import {
     createJingleEvent
 } from '../../service/statistics/AnalyticsEvents';
 import XMPPEvents from '../../service/xmpp/XMPPEvents';
+import FeatureFlags from '../flags/FeatureFlags';
 import Statistics from '../statistics/statistics';
 import GlobalOnErrorHandler from '../util/GlobalOnErrorHandler';
 import RandomUtil from '../util/RandomUtil';
@@ -32,7 +33,8 @@ const logger = getLogger(__filename);
 function _createSourceExtension(owner, sourceCompactJson) {
     const node = $build('source', {
         xmlns: 'urn:xmpp:jingle:apps:rtp:ssma:0',
-        ssrc: sourceCompactJson.s
+        ssrc: sourceCompactJson.s,
+        name: FeatureFlags.isSourceNameSignalingEnabled() ? sourceCompactJson.n : undefined
     });
 
     if (sourceCompactJson.m) {