@webex/plugin-meetings 3.0.0-beta.11 → 3.0.0-beta.111

package/src/meeting/muteState.ts

@@ -1,17 +1,17 @@
+import {ServerMuteReason} from '@webex/media-helpers';
 import LoggerProxy from '../common/logs/logger-proxy';
 import ParameterError from '../common/errors/parameter';
 import PermissionError from '../common/errors/permission';
-import Media from '../media';
-import MeetingUtil from '../meeting/util';
+import MeetingUtil from './util';
 import {AUDIO, VIDEO} from '../constants';
-
-
 /* Certain aspects of server interaction for video muting are not implemented as we currently don't support remote muting of video.
    If we ever need to support it, search for REMOTE_MUTE_VIDEO_MISSING_IMPLEMENTATION string to find the places that need updating
 */
 
-
-const createMuteState = (type, meeting, mediaDirection) => {
+// eslint-disable-next-line import/prefer-default-export
+export const createMuteState = (type, meeting, mediaDirection, sdkOwnsLocalTrack: boolean) => {
+  // todo: remove mediaDirection argument (SPARK-399695)
+  // todo: remove the meeting argument  (SPARK-399695)
   if (type === AUDIO && !mediaDirection.sendAudio) {
     return null;
   }
@@ -19,9 +19,15 @@ const createMuteState = (type, meeting, mediaDirection) => {
     return null;
   }
 
-  LoggerProxy.logger.info(`Meeting:muteState#createMuteState --> ${type}: creating MuteState for meeting id ${meeting?.id}`);
+  LoggerProxy.logger.info(
+    `Meeting:muteState#createMuteState --> ${type}: creating MuteState for meeting id ${meeting?.id}`
+  );
+
+  const muteState = new MuteState(type, meeting, sdkOwnsLocalTrack);
 
-  return new MuteState(type, meeting);
+  muteState.init(meeting);
+
+  return muteState;
 };
 
 /** The purpose of this class is to manage the local and remote mute state and make sure that the server state always matches
@@ -34,35 +40,103 @@ class MuteState {
   pendingPromiseResolve: any;
   state: any;
   type: any;
+  sdkOwnsLocalTrack: boolean; // todo: remove this when doing SPARK-399695
+  ignoreMuteStateChange: boolean;
 
   /**
    * Constructor
    *
    * @param {String} type - audio or video
    * @param {Object} meeting - the meeting object (used for reading current remote mute status)
+   * @param {boolean} sdkOwnsLocalTrack - if false, then client app owns the local track (for now that's the case only for multistream meetings)
    */
-  constructor(type: string, meeting: any) {
-    if ((type !== AUDIO) && (type !== VIDEO)) {
+  constructor(type: string, meeting: any, sdkOwnsLocalTrack: boolean) {
+    if (type !== AUDIO && type !== VIDEO) {
       throw new ParameterError('Mute state is designed for handling audio or video only');
     }
     this.type = type;
+    this.sdkOwnsLocalTrack = sdkOwnsLocalTrack;
+    this.ignoreMuteStateChange = false;
     this.state = {
       client: {
-        localMute: false
+        localMute: false,
       },
       server: {
         localMute: false,
-        // initial values available only for audio (REMOTE_MUTE_VIDEO_MISSING_IMPLEMENTATION)
-        remoteMute: type === AUDIO ? meeting.remoteMuted : false,
-        unmuteAllowed: type === AUDIO ? meeting.unmuteAllowed : true
+        // because remoteVideoMuted and unmuteVideoAllowed are updated seperately, they might be undefined
+        remoteMute: type === AUDIO ? meeting.remoteMuted : meeting.remoteVideoMuted ?? false,
+        unmuteAllowed: type === AUDIO ? meeting.unmuteAllowed : meeting.unmuteVideoAllowed ?? true,
       },
-      syncToServerInProgress: false
+      syncToServerInProgress: false,
     };
     // these 2 hold the resolve, reject methods for the promise we returned to the client in last handleClientRequest() call
     this.pendingPromiseResolve = null;
     this.pendingPromiseReject = null;
   }
 
+  /**
+   * Starts the mute state machine. Needs to be called after a new MuteState instance is created.
+   *
+   * @param {Object} meeting - the meeting object
+   * @returns {void}
+   */
+  public init(meeting: any) {
+    if (!this.sdkOwnsLocalTrack) {
+      this.applyUnmuteAllowedToTrack(meeting);
+
+      // if we are remotely muted, we need to apply that to the local track now (mute on-entry)
+      if (this.state.server.remoteMute) {
+        this.muteLocalTrack(meeting, this.state.server.remoteMute, 'remotelyMuted');
+      }
+
+      const initialMute =
+        this.type === AUDIO
+          ? meeting.mediaProperties.audioTrack?.muted
+          : meeting.mediaProperties.videoTrack?.muted;
+
+      LoggerProxy.logger.info(
+        `Meeting:muteState#start --> ${this.type}: local track initial mute state: ${initialMute}`
+      );
+
+      if (initialMute !== undefined) {
+        this.state.client.localMute = initialMute;
+
+        this.applyClientStateToServer(meeting);
+      }
+    }
+  }
+
+  /**
+   * This method needs to be called whenever the local audio/video track has changed.
+   * It reapplies the remote mute state onto the new track and also reads the current
+   * local mute state from the track and updates the internal state machine and sends
+   * any required requests to the server.
+   *
+   * @param {Object} meeting - the meeting object
+   * @returns {void}
+   */
+  public handleLocalTrackChange(meeting: any) {
+    return this.init(meeting);
+  }
+
+  /**
+   * Mutes/unmutes local track
+   *
+   * @param {Object} meeting - the meeting object
+   * @param {Boolean} mute - true to mute the track, false to unmute it
+   * @param {ServerMuteReason} reason - reason for muting/unmuting
+   * @returns {void}
+   */
+  private muteLocalTrack(meeting: any, mute: boolean, reason: ServerMuteReason) {
+    this.ignoreMuteStateChange = true;
+    if (this.type === AUDIO) {
+      meeting.mediaProperties.audioTrack?.setServerMuted(mute, reason);
+    } else {
+      meeting.mediaProperties.videoTrack?.setServerMuted(mute, reason);
+    }
+    this.ignoreMuteStateChange = false;
+  }
+
   /**
    * Handles mute/unmute request from the client/user. Returns a promise that's resolved once the server update is completed or
    * at the point that this request becomese superseded by another client request.
@@ -77,16 +151,22 @@ class MuteState {
    * @param {Boolean} [mute] true for muting, false for unmuting request
    * @returns {Promise}
    */
-  public handleClientRequest(meeting?: object, mute?: boolean) {
-    LoggerProxy.logger.info(`Meeting:muteState#handleClientRequest --> ${this.type}: user requesting new mute state: ${mute}`);
+  public handleClientRequest(meeting: object, mute?: boolean) {
+    // todo: this whole method will be removed in SPARK-399695
+    LoggerProxy.logger.info(
+      `Meeting:muteState#handleClientRequest --> ${this.type}: user requesting new mute state: ${mute}`
+    );
 
     if (!mute && !this.state.server.unmuteAllowed) {
-      return Promise.reject(new PermissionError('User is not allowed to unmute self (hard mute feature is being used)'));
+      return Promise.reject(
+        new PermissionError('User is not allowed to unmute self (hard mute feature is being used)')
+      );
     }
 
     // we don't check if we're already in the same state, because even if we were, we would still have to apply the mute state locally,
-    // because the client may have changed the audio/vidoe tracks
+    // because the client may have changed the audio/video tracks
     this.state.client.localMute = mute;
+
     this.applyClientStateLocally(meeting);
 
     return new Promise((resolve, reject) => {
@@ -100,19 +180,52 @@ class MuteState {
     });
   }
 
+  /**
+   * This method should be called when the local track mute state is changed
+   * @public
+   * @memberof MuteState
+   * @param {Object} [meeting] the meeting object
+   * @param {Boolean} [mute] true for muting, false for unmuting request
+   * @returns {void}
+   */
+  public handleLocalTrackMuteStateChange(meeting?: object, mute?: boolean) {
+    if (this.ignoreMuteStateChange) {
+      return;
+    }
+    LoggerProxy.logger.info(
+      `Meeting:muteState#handleLocalTrackMuteStateChange --> ${this.type}: local track new mute state: ${mute}`
+    );
+
+    if (this.pendingPromiseReject) {
+      LoggerProxy.logger.error(
+        `Meeting:muteState#handleLocalTrackMuteStateChange --> ${this.type}: Local track mute state change handler called while a client request is handled - this should never happen!, mute state: ${mute}`
+      );
+    }
+
+    this.state.client.localMute = mute;
+
+    this.applyClientStateToServer(meeting);
+  }
+
   /**
    * Applies the current mute state to the local track (by enabling or disabling it accordingly)
    *
    * @public
    * @param {Object} [meeting] the meeting object
+   * @param {ServerMuteReason} reason - reason why we're applying our client state to the local track
    * @memberof MuteState
    * @returns {void}
    */
-  public applyClientStateLocally(meeting?: any) {
-    Media.setLocalTrack(
-      !this.state.client.localMute,
-      (this.type === AUDIO) ? meeting.mediaProperties.audioTrack : meeting.mediaProperties.videoTrack
-    );
+  public applyClientStateLocally(meeting?: any, reason?: ServerMuteReason) {
+    if (this.sdkOwnsLocalTrack) {
+      if (this.type === AUDIO) {
+        meeting.mediaProperties.audioTrack?.setMuted(this.state.client.localMute);
+      } else {
+        meeting.mediaProperties.videoTrack?.setMuted(this.state.client.localMute);
+      }
+    } else {
+      this.muteLocalTrack(meeting, this.state.client.localMute, reason);
+    }
   }
 
   /**
@@ -125,19 +238,27 @@ class MuteState {
    */
   private applyClientStateToServer(meeting?: object) {
     if (this.state.syncToServerInProgress) {
-      LoggerProxy.logger.info(`Meeting:muteState#applyClientStateToServer --> ${this.type}: request to server in progress, we need to wait for it to complete`);
+      LoggerProxy.logger.info(
+        `Meeting:muteState#applyClientStateToServer --> ${this.type}: request to server in progress, we need to wait for it to complete`
+      );
 
       return;
     }
 
-    const localMuteRequiresSync = (this.state.client.localMute !== this.state.server.localMute);
-    const remoteMuteRequiresSync = (!this.state.client.localMute && this.state.server.remoteMute);
+    const localMuteRequiresSync = this.state.client.localMute !== this.state.server.localMute;
+    const remoteMuteRequiresSync = !this.state.client.localMute && this.state.server.remoteMute;
 
-    LoggerProxy.logger.info(`Meeting:muteState#applyClientStateToServer --> ${this.type}: localMuteRequiresSync: ${localMuteRequiresSync} (${this.state.client.localMute} ?= ${this.state.server.localMute})`);
-    LoggerProxy.logger.info(`Meeting:muteState#applyClientStateToServer --> ${this.type}: remoteMuteRequiresSync: ${remoteMuteRequiresSync}`);
+    LoggerProxy.logger.info(
+      `Meeting:muteState#applyClientStateToServer --> ${this.type}: localMuteRequiresSync: ${localMuteRequiresSync} (${this.state.client.localMute} ?= ${this.state.server.localMute})`
+    );
+    LoggerProxy.logger.info(
+      `Meeting:muteState#applyClientStateToServer --> ${this.type}: remoteMuteRequiresSync: ${remoteMuteRequiresSync}`
+    );
 
     if (!localMuteRequiresSync && !remoteMuteRequiresSync) {
-      LoggerProxy.logger.info(`Meeting:muteState#applyClientStateToServer --> ${this.type}: client state already matching server state, nothing to do`);
+      LoggerProxy.logger.info(
+        `Meeting:muteState#applyClientStateToServer --> ${this.type}: client state already matching server state, nothing to do`
+      );
 
       if (this.pendingPromiseResolve) {
         this.pendingPromiseResolve();
@@ -151,15 +272,20 @@ class MuteState {
     this.state.syncToServerInProgress = true;
 
     // first sync local mute with server
-    const localMuteSyncPromise = (localMuteRequiresSync) ? this.sendLocalMuteRequestToServer(meeting) : Promise.resolve();
+    const localMuteSyncPromise = localMuteRequiresSync
+      ? this.sendLocalMuteRequestToServer(meeting)
+      : Promise.resolve();
 
     localMuteSyncPromise
       .then(() =>
         // then follow it up with remote mute sync
-        ((remoteMuteRequiresSync) ? this.sendRemoteMuteRequestToServer(meeting) : Promise.resolve()))
+        remoteMuteRequiresSync ? this.sendRemoteMuteRequestToServer(meeting) : Promise.resolve()
+      )
       .then(() => {
         this.state.syncToServerInProgress = false;
-        LoggerProxy.logger.info(`Meeting:muteState#applyClientStateToServer --> ${this.type}: sync with server completed`);
+        LoggerProxy.logger.info(
+          `Meeting:muteState#applyClientStateToServer --> ${this.type}: sync with server completed`
+        );
 
         // need to check if a new sync is required, because this.state.client may have changed while we were doing the current sync
         this.applyClientStateToServer(meeting);
@@ -172,6 +298,8 @@ class MuteState {
         }
         this.pendingPromiseResolve = null;
         this.pendingPromiseReject = null;
+
+        this.applyServerMuteToLocalTrack(meeting, 'clientRequestFailed');
       });
   }
 
@@ -184,10 +312,14 @@ class MuteState {
    * @returns {Promise}
    */
   private sendLocalMuteRequestToServer(meeting?: any) {
-    const audioMuted = (this.type === AUDIO) ? this.state.client.localMute : meeting.audio?.state.client.localMute;
-    const videoMuted = (this.type === VIDEO) ? this.state.client.localMute : meeting.video?.state.client.localMute;
+    const audioMuted =
+      this.type === AUDIO ? this.state.client.localMute : meeting.audio?.state.client.localMute;
+    const videoMuted =
+      this.type === VIDEO ? this.state.client.localMute : meeting.video?.state.client.localMute;
 
-    LoggerProxy.logger.info(`Meeting:muteState#sendLocalMuteRequestToServer --> ${this.type}: sending local mute (audio=${audioMuted}, video=${videoMuted}) to server`);
+    LoggerProxy.logger.info(
+      `Meeting:muteState#sendLocalMuteRequestToServer --> ${this.type}: sending local mute (audio=${audioMuted}, video=${videoMuted}) to server`
+    );
 
     return MeetingUtil.remoteUpdateAudioVideo(audioMuted, videoMuted, meeting)
       .then((locus) => {
@@ -195,7 +327,7 @@ class MuteState {
           `Meeting:muteState#sendLocalMuteRequestToServer --> ${this.type}: local mute (audio=${audioMuted}, video=${videoMuted}) applied to server`
         );
 
-        this.state.server.localMute = (this.type === AUDIO) ? audioMuted : videoMuted;
+        this.state.server.localMute = this.type === AUDIO ? audioMuted : videoMuted;
 
         meeting.locusInfo.onFullLocus(locus);
 
@@ -210,7 +342,6 @@ class MuteState {
       });
   }
 
-
   /**
    * Sets the remote mute value in the server
    *
@@ -220,32 +351,57 @@ class MuteState {
    * @returns {Promise}
    */
   private sendRemoteMuteRequestToServer(meeting?: any) {
-    if (this.type === AUDIO) {
-      const remoteMute = this.state.client.localMute;
+    const remoteMute = this.state.client.localMute;
 
-      LoggerProxy.logger.info(`Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: sending remote mute:${remoteMute} to server`);
+    LoggerProxy.logger.info(
+      `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: sending remote mute:${remoteMute} to server`
+    );
+
+    return meeting.members
+      .muteMember(meeting.members.selfId, remoteMute, this.type === AUDIO)
+      .then(() => {
+        LoggerProxy.logger.info(
+          `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: remote mute:${remoteMute} applied to server`
+        );
+
+        this.state.server.remoteMute = remoteMute;
+      })
+      .catch((remoteUpdateError) => {
+        LoggerProxy.logger.warn(
+          `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: failed to apply remote mute ${remoteMute} to server: ${remoteUpdateError}`
+        );
 
-      return meeting.members.muteMember(meeting.members.selfId, remoteMute)
-        .then(() => {
-          LoggerProxy.logger.info(
-            `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: remote mute:${remoteMute} applied to server`
-          );
+        return Promise.reject(remoteUpdateError);
+      });
+  }
 
-          this.state.server.remoteMute = remoteMute;
-        })
-        .catch((remoteUpdateError) => {
-          LoggerProxy.logger.warn(
-            `Meeting:muteState#sendRemoteMuteRequestToServer --> ${this.type}: failed to apply remote mute ${remoteMute} to server: ${remoteUpdateError}`
-          );
+  /** Sets the mute state of the local track according to what server thinks is our state
+   * @param {Object} meeting - the meeting object
+   * @param {ServerMuteReason} serverMuteReason - reason why we're applying server mute to the local track
+   * @returns {void}
+   */
+  private applyServerMuteToLocalTrack(meeting: any, serverMuteReason: ServerMuteReason) {
+    if (!this.sdkOwnsLocalTrack) {
+      const muted = this.state.server.localMute || this.state.server.remoteMute;
 
-          return Promise.reject(remoteUpdateError);
-        });
+      // update the local track mute state, but not this.state.client.localMute
+      this.muteLocalTrack(meeting, muted, serverMuteReason);
     }
+  }
 
-    // for now we don't need to support remote muting of video (REMOTE_MUTE_VIDEO_MISSING_IMPLEMENTATION)
-    this.state.server.remoteMute = this.state.client.localMute;
-
-    return Promise.resolve();
+  /** Applies the current value for unmute allowed to the underlying track
+   *
+   * @param {Meeting} meeting
+   * @returns {void}
+   */
+  private applyUnmuteAllowedToTrack(meeting: any) {
+    if (!this.sdkOwnsLocalTrack) {
+      if (this.type === AUDIO) {
+        meeting.mediaProperties.audioTrack?.setUnmuteAllowed(this.state.server.unmuteAllowed);
+      } else {
+        meeting.mediaProperties.videoTrack?.setUnmuteAllowed(this.state.server.unmuteAllowed);
+      }
+    }
   }
 
   /**
@@ -253,14 +409,23 @@ class MuteState {
    *
    * @public
    * @memberof MuteState
+   * @param {Meeting} meeting
    * @param {Boolean} [muted] true if user is remotely muted, false otherwise
    * @param {Boolean} [unmuteAllowed] indicates if user is allowed to unmute self (false when "hard mute" feature is used)
    * @returns {undefined}
    */
-  public handleServerRemoteMuteUpdate(muted?: boolean, unmuteAllowed?: boolean) {
-    LoggerProxy.logger.info(`Meeting:muteState#handleServerRemoteMuteUpdate --> ${this.type}: updating server remoteMute to (${muted})`);
-    this.state.server.remoteMute = muted;
-    this.state.server.unmuteAllowed = unmuteAllowed;
+  public handleServerRemoteMuteUpdate(meeting: any, muted?: boolean, unmuteAllowed?: boolean) {
+    LoggerProxy.logger.info(
+      `Meeting:muteState#handleServerRemoteMuteUpdate --> ${this.type}: updating server remoteMute to (${muted})`
+    );
+    if (unmuteAllowed !== undefined) {
+      this.state.server.unmuteAllowed = unmuteAllowed;
+      this.applyUnmuteAllowedToTrack(meeting);
+    }
+    if (muted !== undefined) {
+      this.state.server.remoteMute = muted;
+      this.applyServerMuteToLocalTrack(meeting, 'remotelyMuted');
+    }
   }
 
   /**
@@ -272,18 +437,23 @@ class MuteState {
    * @returns {undefined}
    */
   public handleServerLocalUnmuteRequired(meeting?: object) {
-    LoggerProxy.logger.info(`Meeting:muteState#handleServerLocalUnmuteRequired --> ${this.type}: localAudioUnmuteRequired received -> doing local unmute`);
+    LoggerProxy.logger.info(
+      `Meeting:muteState#handleServerLocalUnmuteRequired --> ${this.type}: localAudioUnmuteRequired received -> doing local unmute`
+    );
 
+    // todo: I'm seeing "you can now unmute yourself " popup  when this happens - but same thing happens on web.w.c so we can ignore for now
     this.state.server.remoteMute = false;
     this.state.client.localMute = false;
 
     if (this.pendingPromiseReject) {
-      this.pendingPromiseReject(new Error('Server requested local unmute - this overrides any client request in progress'));
+      this.pendingPromiseReject(
+        new Error('Server requested local unmute - this overrides any client request in progress')
+      );
       this.pendingPromiseResolve = null;
       this.pendingPromiseReject = null;
     }
 
-    this.applyClientStateLocally(meeting);
+    this.applyClientStateLocally(meeting, 'localUnmuteRequired');
     this.applyClientStateToServer(meeting);
   }
 
@@ -295,7 +465,42 @@ class MuteState {
    * @returns {Boolean}
    */
   public isMuted() {
-    return this.state.client.localMute || this.state.server.localMute || this.state.server.remoteMute;
+    return (
+      this.state.client.localMute || this.state.server.localMute || this.state.server.remoteMute
+    );
+  }
+
+  /**
+   * Returns true if the user is remotely muted
+   *
+   * @public
+   * @memberof MuteState
+   * @returns {Boolean}
+   */
+  public isRemotelyMuted() {
+    return this.state.server.remoteMute;
+  }
+
+  /**
+   * Returns true if unmute is allowed
+   *
+   * @public
+   * @memberof MuteState
+   * @returns {Boolean}
+   */
+  public isUnmuteAllowed() {
+    return this.state.server.unmuteAllowed;
+  }
+
+  /**
+   * Returns true if the user is locally muted
+   *
+   * @public
+   * @memberof MuteState
+   * @returns {Boolean}
+   */
+  public isLocallyMuted() {
+    return this.state.client.localMute || this.state.server.localMute;
   }
 
   /**
@@ -319,5 +524,3 @@ class MuteState {
     return this.isSelf();
   }
 }
-
-export default createMuteState;