@webex/plugin-meetings 3.0.0-beta.160 → 3.0.0-beta.161

package/src/interpretation/README.md

@@ -0,0 +1,51 @@
+# Simultaneous Interpretation
+
+Simultaneous Interpretation (SI) feature provides support for interpretation of in-meeting audio. The host will specify the target languages at schedule time and assign language pairs to the desired interpreters. Each interpreter will use their client to indicate the language spoken at any point in time. For example, Alice might be translating between English and French. When an English speaker is talking in the meeting, Alice will use her client to indicate she is speaking French. When a French speaker is talking, Alice will indicate that she is speaking English. The host’s client will display the status of each interpreter including the current interpretation direction.
+
+### Structure
+SI languages are available in the siLanguages collection. List the languages which current meeting support to do simultaneous interpretation. Can subscribe the language's voice channel which you want to listen from the list.
+
+```javascript
+interpretation.siLanguages;
+```
+### Attendee functionality
+```javascript
+//subscribe this si language's voice channel
+siLanguage.subscribe();
+
+//unsubscribe this si language's voice channel
+siLanguage.unsubscribe();
+```
+### Host functionality
+The following are methods available to the host of a meeting.
+
+```javascript
+//get the support list of interpretation languages. only host is allowed to call it
+interpretation.getSupportLanguages();
+
+//get the interpreters list of the meeting
+interpretation.getInterpreters();
+
+//update the interpreters list, input parameter is an array of interpreters
+interpretation.updateInterpreters([{
+  sourceLanguage : 'fr-FR',
+  targetLanguage : 'zh-ZH',
+  usingResource : {
+    id : 'a96747e2-1fc6-41d3-9ac7-512dd9478b6e'
+  },
+  order : 0
+},]);
+```
+
+### Interpreter functionality
+
+The following are methods available to the interpreters of a meeting.
+
+```javascript
+//Change direction of interpretation for an interpreter participant
+interpretation.changeDirection();
+
+//Handoff between interpreters, will implement them later
+interpretation.handoff(participantId)
+
+```

package/src/interpretation/collection.ts

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) 2015-2023 Cisco Systems, Inc. See LICENSE file.
+ */
+
+import AmpCollection from 'ampersand-collection';
+
+import {MEETINGS} from '../constants';
+
+import SILanguage from './siLanguage';
+
+const SILanguageCollection = AmpCollection.extend({
+  model: SILanguage,
+
+  namespace: MEETINGS,
+
+  mainIndex: 'languageName',
+});
+
+export default SILanguageCollection;

package/src/interpretation/index.ts

@@ -0,0 +1,182 @@
+/*!
+ * Copyright (c) 2015-2023 Cisco Systems, Inc. See LICENSE file.
+ */
+import {WebexPlugin} from '@webex/webex-core';
+import LoggerProxy from '../common/logs/logger-proxy';
+import {HTTP_VERBS, INTERPRETATION, MEETINGS} from '../constants';
+
+import SILanguageCollection from './collection';
+
+/**
+ * @class SimultaneousInterpretation
+ */
+const SimultaneousInterpretation = WebexPlugin.extend({
+  namespace: MEETINGS,
+  collections: {
+    siLanguages: SILanguageCollection,
+  },
+
+  props: {
+    locusUrl: 'string', // appears current meeting's locus url
+    originalLanguage: 'string', // appears current meeting's original language
+    sourceLanguage: 'string', // appears self interpreter's source language
+    targetLanguage: 'string', // appears self interpreter's target language
+    receiveLanguage: 'string', // appears self's receive language
+    order: 'number', // appears the order of self as interpreter
+    isActive: 'boolean', // appears self is interpreter and is active
+    selfParticipantId: 'string', // appears the self participant id
+    canManageInterpreters: 'boolean', // appears the ability to manage interpreters
+    supportLanguages: 'array', // appears the support languages
+    siEnabled: 'boolean', // appears the meeting enabled SI
+  },
+  derived: {
+    shouldQuerySupportLanguages: {
+      cache: false,
+      deps: ['canManageInterpreters', 'siEnabled'],
+      /**
+       * Returns should query support languages or not
+       * @returns {boolean}
+       */
+      fn() {
+        return !!(this.canManageInterpreters && this.siEnabled);
+      },
+    },
+  },
+  /**
+   * initialize for interpretation
+   * @returns {void}
+   */
+  initialize() {
+    this.listenTo(this, 'change:shouldQuerySupportLanguages', () => {
+      if (this.canManageInterpreters && !this.supportLanguages) {
+        this.querySupportLanguages();
+      }
+    });
+  },
+
+  /**
+   * Calls this to clean up listeners
+   * @returns {void}
+   */
+  cleanUp() {
+    this.stopListening();
+  },
+  /**
+   * Update the current locus url of the meeting
+   * @param {string} locusUrl // locus url
+   * @returns {void}
+   */
+  locusUrlUpdate(locusUrl) {
+    this.set('locusUrl', locusUrl);
+  },
+  /**
+   * Update whether self has capability to manage interpreters (only host can manage it)
+   * @param {boolean} canManageInterpreters
+   * @returns {void}
+   */
+  updateCanManageInterpreters(canManageInterpreters) {
+    this.set('canManageInterpreters', canManageInterpreters);
+  },
+  /**
+   * Update the interpretation languages channels which user can choose to subscribe
+   * @param {Object} interpretation
+   * @returns {void}
+   */
+  updateInterpretation(interpretation) {
+    this.set('siEnabled', !!interpretation);
+    this.siLanguages.set(interpretation?.siLanguages || []);
+  },
+  /**
+   * Update self's interpretation information (self is interpreter)
+   * @param {Object} interpretation
+   * @param {String} selfParticipantId
+   * @returns {void}
+   */
+  updateSelfInterpretation({interpretation, selfParticipantId}) {
+    const {originalLanguage, sourceLanguage, order, isActive, targetLanguage, receiveLanguage} =
+      interpretation || {};
+    this.set({originalLanguage, sourceLanguage, order, isActive, targetLanguage, receiveLanguage});
+    this.set('selfParticipantId', selfParticipantId);
+  },
+  /**
+   * query interpretation languages
+   * @returns {Promise}
+   */
+  querySupportLanguages() {
+    return this.request({
+      method: HTTP_VERBS.GET,
+      uri: `${this.locusUrl}/languages/interpretation`,
+    })
+      .then((result) => {
+        this.set('supportLanguages', result.body?.siLanguages);
+        this.trigger(INTERPRETATION.EVENTS.SUPPORT_LANGUAGES_UPDATE);
+      })
+      .catch((error) => {
+        LoggerProxy.logger.error('Meeting:interpretation#querySupportLanguages failed', error);
+        throw error;
+      });
+  },
+  /**
+   * get interpreters of the meeting
+   * @returns {Promise}
+   */
+  getInterpreters() {
+    return this.request({
+      method: HTTP_VERBS.GET,
+      uri: `${this.locusUrl}/interpretation/interpreters`,
+    }).catch((error) => {
+      LoggerProxy.logger.error('Meeting:interpretation#getInterpreters failed', error);
+      throw error;
+    });
+  },
+  /**
+   * update interpreters of the meeting
+   * @param {Array} interpreters
+   * @returns {Promise}
+   */
+  updateInterpreters(interpreters) {
+    return this.request({
+      method: HTTP_VERBS.PATCH,
+      uri: `${this.locusUrl}/controls`,
+      body: {
+        interpretation: {
+          interpreters,
+        },
+      },
+    }).catch((error) => {
+      LoggerProxy.logger.error('Meeting:interpretation#updateInterpreters failed', error);
+      throw error;
+    });
+  },
+  /**
+   * Change direction of interpretation for an interpreter participant
+   * @returns {Promise}
+   */
+  changeDirection() {
+    if (!this.sourceLanguage || !this.targetLanguage) {
+      return Promise.reject(new Error('Missing sourceLanguage or targetLanguage'));
+    }
+
+    if (!this.selfParticipantId) {
+      return Promise.reject(new Error('Missing self participant id'));
+    }
+
+    return this.request({
+      method: HTTP_VERBS.PATCH,
+      uri: `${this.locusUrl}/participant/${this.selfParticipantId}/controls`,
+      body: {
+        interpretation: {
+          sourceLanguage: this.targetLanguage,
+          targetLanguage: this.sourceLanguage,
+          isActive: this.isActive,
+          order: this.order,
+        },
+      },
+    }).catch((error) => {
+      LoggerProxy.logger.error('Meeting:interpretation#changeDirection failed', error);
+      throw error;
+    });
+  },
+});
+
+export default SimultaneousInterpretation;

package/src/interpretation/siLanguage.ts

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (c) 2015-2023 Cisco Systems, Inc. See LICENSE file.
+ */
+
+import {WebexPlugin} from '@webex/webex-core';
+import {MEETINGS} from '../constants';
+
+const SILanguage = WebexPlugin.extend({
+  idAttribute: 'languageName',
+
+  namespace: MEETINGS,
+  props: {
+    languageCode: 'number',
+    languageName: 'string',
+  },
+});
+
+export default SILanguage;

package/src/locus-info/controlsUtils.ts

@@ -151,6 +151,8 @@ ControlsUtils.getControls = (oldControls: any, newControls: any) => {
 
       hasBreakoutChanged: !isEqual(previous?.breakout, current?.breakout),
 
+      hasInterpretationChanged: !isEqual(previous?.interpretation, current?.interpretation),
+
       hasVideoEnabledChanged:
         newControls.video?.enabled !== undefined &&
         !isEqual(previous?.videoEnabled, current?.videoEnabled),

package/src/locus-info/index.ts

@@ -708,6 +708,7 @@ export default class LocusInfo extends EventsScope {
           hasViewTheParticipantListChanged,
           hasRaiseHandChanged,
           hasVideoChanged,
+          hasInterpretationChanged,
         },
         current,
       } = ControlsUtils.getControls(this.controls, controls);
@@ -845,6 +846,20 @@ export default class LocusInfo extends EventsScope {
         );
       }
 
+      if (hasInterpretationChanged) {
+        const {interpretation} = current;
+        this.emitScoped(
+          {
+            file: 'locus-info',
+            function: 'updateControls',
+          },
+          LOCUSINFO.EVENTS.CONTROLS_MEETING_INTERPRETATION_UPDATED,
+          {
+            interpretation,
+          }
+        );
+      }
+
       if (hasEntryExitToneChanged) {
         const {entryExitTone} = current;
 
@@ -1205,6 +1220,20 @@ export default class LocusInfo extends EventsScope {
         );
       }
 
+      if (parsedSelves.updates.interpretationChanged) {
+        this.emitScoped(
+          {
+            file: 'locus-info',
+            function: 'updateSelf',
+          },
+          LOCUSINFO.EVENTS.SELF_MEETING_INTERPRETATION_CHANGED,
+          {
+            interpretation: parsedSelves.current.interpretation,
+            selfParticipantId: parsedSelves.current.selfId,
+          }
+        );
+      }
+
       if (parsedSelves.updates.isMediaInactiveOrReleased) {
         this.emitScoped(
           {

package/src/locus-info/selfUtils.ts

@@ -65,6 +65,7 @@ SelfUtils.parse = (self: any, deviceId: string) => {
       isSharingBlocked: SelfUtils.isSharingBlocked(self),
       breakoutSessions: SelfUtils.getBreakoutSessions(self),
       breakout: SelfUtils.getBreakout(self),
+      interpretation: SelfUtils.getInterpretation(self),
     };
   }
 
@@ -73,6 +74,7 @@ SelfUtils.parse = (self: any, deviceId: string) => {
 
 SelfUtils.getBreakoutSessions = (self) => self?.controls?.breakout?.sessions;
 SelfUtils.getBreakout = (self) => self?.controls?.breakout;
+SelfUtils.getInterpretation = (self) => self?.controls?.interpretation;
 
 SelfUtils.getLayout = (self) =>
   Array.isArray(self?.controls?.layouts) ? self.controls.layouts[0].type : undefined;
@@ -125,6 +127,7 @@ SelfUtils.getSelves = (oldSelf, newSelf, deviceId) => {
     previous?.canNotViewTheParticipantList !== current.canNotViewTheParticipantList;
   updates.isSharingBlockedChanged = previous?.isSharingBlocked !== current.isSharingBlocked;
   updates.breakoutsChanged = SelfUtils.breakoutsChanged(previous, current);
+  updates.interpretationChanged = SelfUtils.interpretationChanged(previous, current);
 
   return {
     previous,
@@ -153,6 +156,9 @@ SelfUtils.layoutChanged = (previous: any, current: any) =>
 SelfUtils.breakoutsChanged = (previous, current) =>
   !isEqual(previous?.breakoutSessions, current?.breakoutSessions) && !!current?.breakout;
 
+SelfUtils.interpretationChanged = (previous, current) =>
+  !isEqual(previous?.interpretation, current?.interpretation) && !!current?.interpretation;
+
 SelfUtils.isMediaInactive = (previous, current) => {
   if (
     previous &&

package/src/meeting/index.ts

@@ -88,6 +88,7 @@ import {
   VIDEO,
   HTTP_VERBS,
   SELF_ROLES,
+  INTERPRETATION,
 } from '../constants';
 import BEHAVIORAL_METRICS from '../metrics/constants';
 import ParameterError from '../common/errors/parameter';
@@ -112,6 +113,7 @@ import {
   RelayEvent,
 } from '../reactions/reactions.type';
 import Breakouts from '../breakouts';
+import SimultaneousInterpretation from '../interpretation';
 import Annotation from '../annotation';
 
 import InMeetingActions from './in-meeting-actions';
@@ -437,6 +439,7 @@ export default class Meeting extends StatelessWebexPlugin {
   attrs: any;
   audio: any;
   breakouts: any;
+  simultaneousInterpretation: any;
   annotation: any;
   conversationUrl: string;
   correlationId: string;
@@ -626,6 +629,14 @@ export default class Meeting extends StatelessWebexPlugin {
      */
     // @ts-ignore
     this.breakouts = new Breakouts({meetingId: this.id}, {parent: this.webex});
+    /**
+     * @instance
+     * @type {SimultaneousInterpretation}
+     * @public
+     * @memberof Meeting
+     */
+    // @ts-ignore
+    this.simultaneousInterpretation = new SimultaneousInterpretation({}, {parent: this.webex});
     /**
      * @instance
      * @type {Annotation}
@@ -1468,6 +1479,7 @@ export default class Meeting extends StatelessWebexPlugin {
     this.setUpLocusInfoAssignHostListener();
     this.setUpLocusInfoMediaInactiveListener();
     this.setUpBreakoutsListener();
+    this.setUpInterpretationListener();
   }
 
   /**
@@ -1559,6 +1571,25 @@ export default class Meeting extends StatelessWebexPlugin {
     });
   }
 
+  /**
+   * Set up the listeners for interpretation
+   * @returns {undefined}
+   * @private
+   * @memberof Meeting
+   */
+  private setUpInterpretationListener() {
+    this.simultaneousInterpretation.on(INTERPRETATION.EVENTS.SUPPORT_LANGUAGES_UPDATE, () => {
+      Trigger.trigger(
+        this,
+        {
+          file: 'meeting/index',
+          function: 'setUpInterpretationListener',
+        },
+        EVENT_TRIGGERS.MEETING_INTERPRETATION_SUPPORT_LANGUAGES_UPDATE
+      );
+    });
+  }
+
   /**
    * Set up the locus info listener for meetings disconnected due to inactivity
    * @returns {undefined}
@@ -2131,6 +2162,21 @@ export default class Meeting extends StatelessWebexPlugin {
       );
     });
 
+    this.locusInfo.on(
+      LOCUSINFO.EVENTS.CONTROLS_MEETING_INTERPRETATION_UPDATED,
+      ({interpretation}) => {
+        this.simultaneousInterpretation.updateInterpretation(interpretation);
+        Trigger.trigger(
+          this,
+          {
+            file: 'meeting/index',
+            function: 'setupLocusControlsListener',
+          },
+          EVENT_TRIGGERS.MEETING_INTERPRETATION_UPDATE
+        );
+      }
+    );
+
     this.locusInfo.on(LOCUSINFO.EVENTS.CONTROLS_JOIN_BREAKOUT_FROM_MAIN, ({mainLocusUrl}) => {
       this.meetingRequest.getLocusStatusByUrl(mainLocusUrl).catch((error) => {
         // clear main session cache when attendee join into breakout and forbidden to get locus from main locus url,
@@ -2479,6 +2525,7 @@ export default class Meeting extends StatelessWebexPlugin {
     this.locusInfo.on(EVENTS.LOCUS_INFO_UPDATE_URL, (payload) => {
       this.members.locusUrlUpdate(payload);
       this.breakouts.locusUrlUpdate(payload);
+      this.simultaneousInterpretation.locusUrlUpdate(payload);
       this.annotation.locusUrlUpdate(payload);
       this.locusUrl = payload;
       this.locusId = this.locusUrl?.split('/').pop();
@@ -2944,12 +2991,26 @@ export default class Meeting extends StatelessWebexPlugin {
       );
     });
 
+    this.locusInfo.on(LOCUSINFO.EVENTS.SELF_MEETING_INTERPRETATION_CHANGED, (payload) => {
+      this.simultaneousInterpretation.updateSelfInterpretation(payload);
+      Trigger.trigger(
+        this,
+        {
+          file: 'meeting/index',
+          function: 'setUpLocusInfoSelfListener',
+        },
+        EVENT_TRIGGERS.MEETING_INTERPRETATION_UPDATE
+      );
+    });
+
     this.locusInfo.on(LOCUSINFO.EVENTS.SELF_ROLES_CHANGED, (payload) => {
       const isModeratorOrCohost =
         payload.newRoles?.includes(SELF_ROLES.MODERATOR) ||
         payload.newRoles?.includes(SELF_ROLES.COHOST);
       this.breakouts.updateCanManageBreakouts(isModeratorOrCohost);
-
+      this.simultaneousInterpretation.updateCanManageInterpreters(
+        payload.newRoles?.includes(SELF_ROLES.MODERATOR)
+      );
       Trigger.trigger(
         this,
         {

package/src/meeting/util.ts

@@ -129,6 +129,7 @@ const MeetingUtil = {
 
   cleanUp: (meeting) => {
     meeting.breakouts.cleanUp();
+    meeting.simultaneousInterpretation.cleanUp();
 
     // make sure we send last metrics before we close the peerconnection
     const stopStatsAnalyzer = meeting.statsAnalyzer

package/src/member/index.ts

@@ -34,6 +34,7 @@ export default class Member {
   participant: any;
   status: any;
   supportsBreakouts: boolean;
+  supportsInterpretation: boolean;
   supportLiveAnnotation: boolean;
   type: any;
   namespace = MEETINGS;
@@ -269,6 +270,7 @@ export default class Member {
       this.isVideoMuted = MemberUtil.isVideoMuted(participant);
       this.isHandRaised = MemberUtil.isHandRaised(participant);
       this.supportsBreakouts = MemberUtil.isBreakoutsSupported(participant);
+      this.supportsInterpretation = MemberUtil.isInterpretationSupported(participant);
       this.supportLiveAnnotation = MemberUtil.isLiveAnnotationSupported(participant);
       this.isGuest = MemberUtil.isGuest(participant);
       this.isUser = MemberUtil.isUser(participant);

package/src/member/util.ts

@@ -196,6 +196,20 @@ MemberUtil.isBreakoutsSupported = (participant) => {
   return !participant.doesNotSupportBreakouts;
 };
 
+/**
+ * @param {Object} participant the locus participant
+ * @returns {Boolean}
+ */
+MemberUtil.isInterpretationSupported = (participant) => {
+  if (!participant) {
+    throw new ParameterError(
+      'Interpretation support could not be processed, participant is undefined.'
+    );
+  }
+
+  return !participant.doesNotSupportSiInterpreter;
+};
+
 /**
  * @param {Object} participant the locus participant
  * @returns {Boolean}

package/test/unit/spec/interpretation/collection.ts

@@ -0,0 +1,15 @@
+import {assert} from '@webex/test-helper-chai';
+import SILanguage from '@webex/plugin-meetings/src/interpretation/siLanguage';
+import SILanguageCollection from '@webex/plugin-meetings/src/interpretation/collection';
+
+describe('plugin-meetings', () => {
+  describe('SILanguageCollection', () => {
+    it('the siLanguages collection is as expected', () => {
+      const collection = new SILanguageCollection();
+
+      assert.equal(collection.model, SILanguage);
+      assert.equal(collection.namespace, 'Meetings');
+      assert.equal(collection.mainIndex, 'languageName');
+    });
+  });
+});