@webex/plugin-meetings 2.59.8 → 2.60.0-next.2

package/src/multistream/receiveSlotManager.ts

@@ -0,0 +1,166 @@
+/* eslint-disable valid-jsdoc */
+/* eslint-disable import/prefer-default-export */
+import {MediaType, ReceiveSlot as WcmeReceiveSlot} from '@webex/internal-media-core';
+import LoggerProxy from '../common/logs/logger-proxy';
+
+import {FindMemberIdCallback, ReceiveSlot} from './receiveSlot';
+
+export type CreateSlotCallback = (mediaType: MediaType) => Promise<WcmeReceiveSlot>;
+
+export type {CSI, FindMemberIdCallback} from './receiveSlot';
+
+/**
+ * Manages all receive slots used by a meeting. WMCE receive slots cannot be ever deleted,
+ * so this manager has a pool in order to re-use the slots that were released earlier.
+ */
+export class ReceiveSlotManager {
+  private allocatedSlots: {[key in MediaType]: ReceiveSlot[]};
+
+  private freeSlots: {[key in MediaType]: ReceiveSlot[]};
+
+  private createSlotCallback: CreateSlotCallback;
+
+  private findMemberIdByCsiCallback: FindMemberIdCallback;
+
+  /**
+   * Constructor
+   * @param {Meeting} meeting
+   */
+  constructor(
+    createSlotCallback: CreateSlotCallback,
+    findMemberIdByCsiCallback: FindMemberIdCallback
+  ) {
+    this.allocatedSlots = {
+      [MediaType.AudioMain]: [],
+      [MediaType.VideoMain]: [],
+      [MediaType.AudioSlides]: [],
+      [MediaType.VideoSlides]: [],
+    };
+    this.freeSlots = {
+      [MediaType.AudioMain]: [],
+      [MediaType.VideoMain]: [],
+      [MediaType.AudioSlides]: [],
+      [MediaType.VideoSlides]: [],
+    };
+    this.createSlotCallback = createSlotCallback;
+    this.findMemberIdByCsiCallback = findMemberIdByCsiCallback;
+  }
+
+  /**
+   * Creates a new receive slot or returns one from the existing pool of free slots
+   *
+   * @param {MediaType} mediaType
+   * @returns {Promise<ReceiveSlot>}
+   */
+  async allocateSlot(mediaType: MediaType): Promise<ReceiveSlot> {
+    // try to use one of the free ones
+    const availableSlot = this.freeSlots[mediaType].pop();
+
+    if (availableSlot) {
+      this.allocatedSlots[mediaType].push(availableSlot);
+
+      LoggerProxy.logger.log(`${mediaType}: receive slot re-used: ${availableSlot.id}`);
+
+      return availableSlot;
+    }
+
+    // we have to create a new one
+    const wcmeReceiveSlot = await this.createSlotCallback(mediaType);
+
+    const receiveSlot = new ReceiveSlot(mediaType, wcmeReceiveSlot, this.findMemberIdByCsiCallback);
+
+    this.allocatedSlots[mediaType].push(receiveSlot);
+    LoggerProxy.logger.log(`${mediaType}: new receive slot allocated: ${receiveSlot.id}`);
+
+    return receiveSlot;
+  }
+
+  /**
+   * Releases the slot back to the pool so it can be re-used by others in the future
+   * @param {ReceiveSlot} slot
+   */
+  releaseSlot(slot: ReceiveSlot) {
+    const idx = this.allocatedSlots[slot.mediaType].findIndex(
+      (allocatedSlot) => allocatedSlot === slot
+    );
+
+    if (idx >= 0) {
+      this.allocatedSlots[slot.mediaType].splice(idx, 1);
+      this.freeSlots[slot.mediaType].push(slot);
+      LoggerProxy.logger.log(`${slot.mediaType}: receive slot released: ${slot.id}`);
+    } else {
+      LoggerProxy.logger.warn(
+        `ReceiveSlotManager#releaseSlot --> trying to release a ${slot.mediaType}} slot that is not managed by this ReceiveSlotManager`
+      );
+    }
+  }
+
+  /**
+   * Resets the slot manager - this method should be called when the media connection is torn down
+   */
+  reset() {
+    this.allocatedSlots = {
+      [MediaType.AudioMain]: [],
+      [MediaType.VideoMain]: [],
+      [MediaType.AudioSlides]: [],
+      [MediaType.VideoSlides]: [],
+    };
+    this.freeSlots = {
+      [MediaType.AudioMain]: [],
+      [MediaType.VideoMain]: [],
+      [MediaType.AudioSlides]: [],
+      [MediaType.VideoSlides]: [],
+    };
+  }
+
+  /**
+   * Returns statistics about the managed slots
+   *
+   * @returns {Object}
+   */
+  getStats() {
+    const numAllocatedSlots = {};
+    const numFreeSlots = {};
+
+    Object.keys(this.allocatedSlots).forEach((key) => {
+      if (this.allocatedSlots[key].length > 0) {
+        numAllocatedSlots[key] = this.allocatedSlots[key].length;
+      }
+    });
+
+    Object.keys(this.freeSlots).forEach((key) => {
+      if (this.freeSlots[key].length > 0) {
+        numFreeSlots[key] = this.freeSlots[key].length;
+      }
+    });
+
+    return {
+      numAllocatedSlots,
+      numFreeSlots,
+    };
+  }
+
+  /**
+   * Tries to find the member id on all allocated receive slots
+   * This function should be called when new members are added to the meeting.
+   */
+  updateMemberIds() {
+    Object.keys(this.allocatedSlots).forEach((key) => {
+      this.allocatedSlots[key].forEach((slot: ReceiveSlot) => {
+        slot.findMemberId();
+      });
+    });
+  }
+
+  /**
+   * Find a receive slot by a ssrc.
+   *
+   * @param ssrc - The ssrc of the receive slot to find.
+   * @returns - The receive slot with this ssrc, undefined if not found.
+   */
+  findReceiveSlotBySsrc(ssrc: number): ReceiveSlot | undefined {
+    return Object.values(this.allocatedSlots)
+      .flat()
+      .find((r) => ssrc && r.wcmeReceiveSlot?.id?.ssrc === ssrc);
+  }
+}

package/src/multistream/remoteMedia.ts

@@ -0,0 +1,254 @@
+/* eslint-disable valid-jsdoc */
+import {MediaType, StreamState} from '@webex/internal-media-core';
+import LoggerProxy from '../common/logs/logger-proxy';
+import EventsScope from '../common/events/events-scope';
+
+import {MediaRequestId, MediaRequestManager} from './mediaRequestManager';
+import {CSI, ReceiveSlot, ReceiveSlotEvents} from './receiveSlot';
+
+export const RemoteMediaEvents = {
+  SourceUpdate: ReceiveSlotEvents.SourceUpdate,
+  Stopped: 'stopped',
+};
+
+export type RemoteVideoResolution =
+  | 'thumbnail' // the smallest possible resolution, 90p or less
+  | 'very small' // 180p or less
+  | 'small' // 360p or less
+  | 'medium' // 720p or less
+  | 'large' // 1080p or less
+  | 'best'; // highest possible resolution
+
+/**
+ * Converts pane size into h264 maxFs
+ * @param {PaneSize} paneSize
+ * @returns {number}
+ */
+export function getMaxFs(paneSize: RemoteVideoResolution): number {
+  let maxFs;
+
+  switch (paneSize) {
+    case 'thumbnail':
+      maxFs = 60;
+      break;
+    case 'very small':
+      maxFs = 240;
+      break;
+    case 'small':
+      maxFs = 920;
+      break;
+    case 'medium':
+      maxFs = 3600;
+      break;
+    case 'large':
+      maxFs = 8192;
+      break;
+    case 'best':
+      maxFs = 8192; // for now 'best' is 1080p, so same as 'large'
+      break;
+    default:
+      LoggerProxy.logger.warn(
+        `RemoteMedia#getMaxFs --> unsupported paneSize: ${paneSize}, using "medium" instead`
+      );
+      maxFs = 3600;
+  }
+
+  return maxFs;
+}
+
+type Options = {
+  resolution?: RemoteVideoResolution; // applies only to groups of type MediaType.VideoMain and MediaType.VideoSlides
+};
+
+export type RemoteMediaId = string;
+
+let remoteMediaCounter = 0;
+
+/**
+ * Class representing a remote audio/video stream.
+ *
+ * Internally it is associated with a specific receive slot
+ * and a media request for it.
+ */
+export class RemoteMedia extends EventsScope {
+  private receiveSlot?: ReceiveSlot;
+
+  private readonly mediaRequestManager: MediaRequestManager;
+
+  private readonly options: Options;
+
+  private mediaRequestId?: MediaRequestId;
+
+  public readonly id: RemoteMediaId;
+
+  /**
+   * Constructs RemoteMedia instance
+   *
+   * @param receiveSlot
+   * @param mediaRequestManager
+   * @param options
+   */
+  constructor(
+    receiveSlot: ReceiveSlot,
+    mediaRequestManager: MediaRequestManager,
+    options?: Options
+  ) {
+    super();
+    remoteMediaCounter += 1;
+    this.receiveSlot = receiveSlot;
+    this.mediaRequestManager = mediaRequestManager;
+    this.options = options || {};
+    this.setupEventListeners();
+    this.id = `RM${remoteMediaCounter}-${this.receiveSlot.id}`;
+  }
+
+  /**
+   * Supply the width and height of the video element
+   * to restrict the requested resolution to this size
+   * @param width width of the video element
+   * @param height height of the video element
+   */
+  public setSizeHint(width, height) {
+    // only base on height for now
+    let fs: number;
+
+    if (height < 135) {
+      fs = 60;
+    } else if (height < 270) {
+      fs = 240;
+    } else if (height < 540) {
+      fs = 920;
+    } else if (height <= 720) {
+      fs = 3600;
+    } else {
+      fs = 8192;
+    }
+
+    this.receiveSlot?.setMaxFs(fs);
+  }
+
+  /**
+   * Invalidates the remote media by clearing the reference to a receive slot and
+   * cancelling the media request.
+   * After this call the remote media is unusable.
+   *
+   * @param {boolean} commit - whether to commit the cancellation of the media request
+   * @internal
+   */
+  public stop(commit = true) {
+    this.cancelMediaRequest(commit);
+    this.receiveSlot?.removeAllListeners();
+    this.receiveSlot = undefined;
+    this.emit(
+      {
+        file: 'multistream/remoteMedia',
+        function: 'stop',
+      },
+      RemoteMediaEvents.Stopped,
+      {}
+    );
+  }
+
+  /**
+   * Sends a new media request. This method can only be used for receiver-selected policy,
+   * because only in that policy we have a 1-1 relationship between RemoteMedia and MediaRequest
+   * and the request id is then stored in this RemoteMedia instance.
+   * For active-speaker policy, the same request is shared among many RemoteMedia instances,
+   * so it's managed through RemoteMediaGroup
+   *
+   * @internal
+   */
+  public sendMediaRequest(csi: CSI, commit: boolean) {
+    if (this.mediaRequestId) {
+      this.cancelMediaRequest(false);
+    }
+
+    if (!this.receiveSlot) {
+      throw new Error('sendMediaRequest() called on an invalidated RemoteMedia instance');
+    }
+
+    this.mediaRequestId = this.mediaRequestManager.addRequest(
+      {
+        policyInfo: {
+          policy: 'receiver-selected',
+          csi,
+        },
+        receiveSlots: [this.receiveSlot],
+        codecInfo: this.options.resolution && {
+          codec: 'h264',
+          maxFs: getMaxFs(this.options.resolution),
+        },
+      },
+      commit
+    );
+  }
+
+  /**
+   * @internal
+   */
+  public cancelMediaRequest(commit: boolean) {
+    if (this.mediaRequestId) {
+      this.mediaRequestManager.cancelRequest(this.mediaRequestId, commit);
+      this.mediaRequestId = undefined;
+    }
+  }
+
+  /**
+   * registers event listeners on the receive slot and forwards all the events
+   */
+  private setupEventListeners() {
+    if (this.receiveSlot) {
+      const scope = {
+        file: 'multistream/remoteMedia',
+        function: 'setupEventListeners',
+      };
+
+      this.receiveSlot.on(ReceiveSlotEvents.SourceUpdate, (data) => {
+        this.emit(scope, RemoteMediaEvents.SourceUpdate, data);
+      });
+    }
+  }
+
+  /**
+   * Getter for mediaType
+   */
+  public get mediaType(): MediaType {
+    return this.receiveSlot?.mediaType;
+  }
+
+  /**
+   * Getter for memberId
+   */
+  public get memberId() {
+    return this.receiveSlot?.memberId;
+  }
+
+  /**
+   * Getter for csi
+   */
+  public get csi() {
+    return this.receiveSlot?.csi;
+  }
+
+  /**
+   * Getter for source state
+   */
+  public get sourceState(): StreamState {
+    return this.receiveSlot?.sourceState;
+  }
+
+  /**
+   * Getter for remote media stream
+   */
+  public get stream() {
+    return this.receiveSlot?.stream;
+  }
+
+  /**
+   * @internal
+   * @returns {ReceiveSlot}
+   */
+  public getUnderlyingReceiveSlot() {
+    return this.receiveSlot;
+  }
+}

package/src/multistream/remoteMediaGroup.ts

@@ -0,0 +1,284 @@
+/* eslint-disable valid-jsdoc */
+/* eslint-disable require-jsdoc */
+/* eslint-disable import/prefer-default-export */
+import {forEach} from 'lodash';
+import LoggerProxy from '../common/logs/logger-proxy';
+
+import {getMaxFs, RemoteMedia, RemoteVideoResolution} from './remoteMedia';
+import {MediaRequestId, MediaRequestManager} from './mediaRequestManager';
+import {CSI, ReceiveSlot} from './receiveSlot';
+
+type Options = {
+  resolution?: RemoteVideoResolution; // applies only to groups of type MediaType.VideoMain and MediaType.VideoSlides
+  preferLiveVideo?: boolean; // applies only to groups of type MediaType.VideoMain and MediaType.VideoSlides
+};
+
+export class RemoteMediaGroup {
+  private mediaRequestManager: MediaRequestManager;
+
+  private priority: number;
+
+  private options: Options;
+
+  private unpinnedRemoteMedia: RemoteMedia[];
+
+  private mediaRequestId?: MediaRequestId; // id of the "active-speaker" media request id
+
+  private pinnedRemoteMedia: RemoteMedia[];
+
+  constructor(
+    mediaRequestManager: MediaRequestManager,
+    receiveSlots: ReceiveSlot[],
+    priority: number,
+    commitMediaRequest: boolean,
+    options: Options = {}
+  ) {
+    this.mediaRequestManager = mediaRequestManager;
+    this.priority = priority;
+    this.options = options;
+
+    this.unpinnedRemoteMedia = receiveSlots.map(
+      (slot) =>
+        new RemoteMedia(slot, this.mediaRequestManager, {
+          resolution: this.options.resolution,
+        })
+    );
+    this.pinnedRemoteMedia = [];
+
+    this.sendActiveSpeakerMediaRequest(commitMediaRequest);
+  }
+
+  /**
+   * Gets the array of remote media elements from the group
+   *
+   * @param {string} filter - 'all' (default) returns both pinned and unpinned
+   * @returns {Array<RemoteMedia>}
+   */
+  public getRemoteMedia(filter: 'all' | 'pinned' | 'unpinned' = 'all') {
+    if (filter === 'unpinned') {
+      // return a shallow copy so that the client cannot modify this.unpinnedRemoteMedia array
+      return [...this.unpinnedRemoteMedia];
+    }
+    if (filter === 'pinned') {
+      // return a shallow copy so that the client cannot modify this.pinnedRemoteMedia array
+      return [...this.pinnedRemoteMedia];
+    }
+
+    return [...this.unpinnedRemoteMedia, ...this.pinnedRemoteMedia];
+  }
+
+  /**
+   * Sets CSIs for multiple RemoteMedia instances belonging to this RemoteMediaGroup.
+   * For each entry in the remoteMediaCsis array:
+   * - if csi is specified, the RemoteMedia instance is pinned to that CSI
+   * - if csi is undefined, the RemoteMedia instance is unpinned
+   * @internal
+   */
+  public setActiveSpeakerCsis(
+    remoteMediaCsis: {remoteMedia: RemoteMedia; csi?: number}[],
+    commit = true
+  ): void {
+    forEach(remoteMediaCsis, ({csi, remoteMedia}) => {
+      if (csi) {
+        if (!(this.pinnedRemoteMedia.indexOf(remoteMedia) >= 0)) {
+          const unpinId = this.unpinnedRemoteMedia.indexOf(remoteMedia);
+          if (unpinId >= 0) {
+            this.unpinnedRemoteMedia.splice(unpinId, 1);
+            this.pinnedRemoteMedia.push(remoteMedia);
+          } else {
+            throw new Error(
+              `failed to pin a remote media object ${remoteMedia.id}, because it is not found in this remote media group`
+            );
+          }
+        }
+        remoteMedia.sendMediaRequest(csi, false);
+      } else {
+        if (!(this.unpinnedRemoteMedia.indexOf(remoteMedia) >= 0)) {
+          const pinId = this.pinnedRemoteMedia.indexOf(remoteMedia);
+          if (pinId >= 0) {
+            this.pinnedRemoteMedia.splice(pinId, 1);
+            this.unpinnedRemoteMedia.push(remoteMedia);
+          } else {
+            throw new Error(
+              `failed to unpin a remote media object ${remoteMedia.id}, because it is not found in this remote media group`
+            );
+          }
+        }
+        remoteMedia.cancelMediaRequest(false);
+      }
+    });
+    this.cancelActiveSpeakerMediaRequest(false);
+    this.sendActiveSpeakerMediaRequest(false);
+    if (commit) {
+      this.mediaRequestManager.commit();
+    }
+  }
+
+  /**
+   * Pins a specific remote media instance to a specfic CSI, so the media will
+   * no longer come from active speaker, but from that CSI.
+   * If no CSI is given, the current CSI value is used.
+   *
+   */
+  public pin(remoteMedia: RemoteMedia, csi?: CSI): void {
+    // if csi is not specified, use the current one
+    const targetCsi = csi || remoteMedia.csi;
+
+    if (!targetCsi) {
+      throw new Error(
+        `failed to pin a remote media object ${remoteMedia.id}, because it has no CSI set and no CSI value was given`
+      );
+    }
+
+    if (this.pinnedRemoteMedia.indexOf(remoteMedia) >= 0) {
+      if (targetCsi === remoteMedia.csi) {
+        // remote media already pinned to target CSI, nothing to do
+        LoggerProxy.logger.log(
+          `RemoteMediaGroup#pin --> remote media ${remoteMedia.id} already pinned`
+        );
+
+        return;
+      }
+    } else {
+      const idx = this.unpinnedRemoteMedia.indexOf(remoteMedia);
+
+      if (idx < 0) {
+        throw new Error(
+          `failed to pin a remote media object ${remoteMedia.id}, because it is not found in this remote media group`
+        );
+      }
+
+      this.unpinnedRemoteMedia.splice(idx, 1);
+      this.pinnedRemoteMedia.push(remoteMedia);
+
+      this.cancelActiveSpeakerMediaRequest(false);
+      this.sendActiveSpeakerMediaRequest(false);
+    }
+
+    remoteMedia.sendMediaRequest(targetCsi, false);
+    this.mediaRequestManager.commit();
+  }
+
+  /**
+   * Unpins a remote media instance, so that it will again provide media from active speakers
+   *
+   */
+  public unpin(remoteMedia: RemoteMedia) {
+    if (this.unpinnedRemoteMedia.indexOf(remoteMedia) >= 0) {
+      LoggerProxy.logger.log(
+        `RemoteMediaGroup#pin --> remote media ${remoteMedia.id} already unpinned`
+      );
+
+      return;
+    }
+    const idx = this.pinnedRemoteMedia.indexOf(remoteMedia);
+
+    if (idx < 0) {
+      throw new Error(
+        `failed to unpin a remote media object ${remoteMedia.id}, because it is not found in this remote media group`
+      );
+    }
+
+    this.pinnedRemoteMedia.splice(idx, 1);
+    this.unpinnedRemoteMedia.push(remoteMedia);
+
+    remoteMedia.cancelMediaRequest(false);
+    this.cancelActiveSpeakerMediaRequest(false);
+    this.sendActiveSpeakerMediaRequest(false);
+    this.mediaRequestManager.commit();
+  }
+
+  public isPinned(remoteMedia: RemoteMedia) {
+    if (this.unpinnedRemoteMedia.indexOf(remoteMedia) >= 0) {
+      return false;
+    }
+    if (this.pinnedRemoteMedia.indexOf(remoteMedia) >= 0) {
+      return true;
+    }
+
+    throw new Error(`remote media object ${remoteMedia.id} not found in the group`);
+  }
+
+  /**
+   * setPreferLiveVideo - sets preferLiveVideo to true/false
+   * @internal
+   */
+  public setPreferLiveVideo(preferLiveVideo: boolean, commit: boolean) {
+    if (this.options.preferLiveVideo !== preferLiveVideo) {
+      this.options.preferLiveVideo = preferLiveVideo;
+      this.sendActiveSpeakerMediaRequest(commit);
+    }
+  }
+
+  private sendActiveSpeakerMediaRequest(commit: boolean) {
+    this.cancelActiveSpeakerMediaRequest(false);
+
+    this.mediaRequestId = this.mediaRequestManager.addRequest(
+      {
+        policyInfo: {
+          policy: 'active-speaker',
+          priority: this.priority,
+          crossPriorityDuplication: false,
+          crossPolicyDuplication: false,
+          preferLiveVideo: !!this.options?.preferLiveVideo,
+        },
+        receiveSlots: this.unpinnedRemoteMedia.map((remoteMedia) =>
+          remoteMedia.getUnderlyingReceiveSlot()
+        ) as ReceiveSlot[],
+        codecInfo: this.options.resolution && {
+          codec: 'h264',
+          maxFs: getMaxFs(this.options.resolution),
+        },
+      },
+      commit
+    );
+  }
+
+  private cancelActiveSpeakerMediaRequest(commit: boolean) {
+    if (this.mediaRequestId) {
+      this.mediaRequestManager.cancelRequest(this.mediaRequestId, commit);
+      this.mediaRequestId = undefined;
+    }
+  }
+
+  /**
+   * Invalidates the remote media group by clearing the references to the receive slots
+   * used by all remote media from that group and cancelling all media requests.
+   * After this call the remote media group is unusable.
+   *
+   * @param{boolean} commit whether to commit the cancellation of media requests
+   * @internal
+   */
+  public stop(commit = true) {
+    this.unpinnedRemoteMedia.forEach((remoteMedia) => remoteMedia.stop(false));
+    this.pinnedRemoteMedia.forEach((remoteMedia) => remoteMedia.stop(false));
+    this.cancelActiveSpeakerMediaRequest(false);
+
+    if (commit) {
+      this.mediaRequestManager.commit();
+    }
+  }
+
+  /**
+   * Checks if a given RemoteMedia instance belongs to this group.
+   *
+   * @param remoteMedia RemoteMedia instance to check
+   * @param filter controls which remote media from the group to check
+   * @returns true if remote media is found
+   */
+  public includes(
+    remoteMedia: RemoteMedia,
+    filter: 'all' | 'pinned' | 'unpinned' = 'all'
+  ): boolean {
+    if (filter === 'pinned') {
+      return this.pinnedRemoteMedia.includes(remoteMedia);
+    }
+    if (filter === 'unpinned') {
+      return this.unpinnedRemoteMedia.includes(remoteMedia);
+    }
+
+    return (
+      this.unpinnedRemoteMedia.includes(remoteMedia) || this.pinnedRemoteMedia.includes(remoteMedia)
+    );
+  }
+}