Merge feature branch for VDI support

.circleci/config.yml

@@ -78,12 +78,12 @@ commands:
  - store_artifacts:
  path: ./dist
  prefix: ./dist
- unit-tests:
+ build-checks:
  steps:
  - build
  - run:
- name: Running unit tests
- command: npm run test:unit
+ name: Running build checks
+ command: npm run test:typecheck && npm run lint && npm run test:unit
  - store_artifacts:
  path: coverage
  destination: coverage
@@ -105,9 +105,9 @@ commands:
 # Jobs
 ###
 jobs:
- run-unit-tests:
+ run-build-checks:
  executor: docker-with-browser
- steps: [unit-tests]
+ steps: [build-checks]
  run-network-tests:
  parameters:
  bver:
@@ -174,10 +174,10 @@ workflows:
  - equal: [true, <<pipeline.parameters.pr_workflow>>]
  - equal: [false, <<pipeline.parameters.release_workflow>>]
  jobs:
- - run-unit-tests:
+ - run-build-checks:
  context:
  - vblocks-js
- name: Unit Tests
+ name: Build Checks
  - run-integration-tests:
  name: Integration Tests <<matrix.browser>> <<matrix.bver>>
  context:
@@ -200,10 +200,10 @@ workflows:
  release-workflow:
  when: <<pipeline.parameters.release_workflow>>
  jobs:
- - run-unit-tests:
+ - run-build-checks:
  context:
  - vblocks-js
- name: Unit Tests
+ name: Build Checks
  - run-integration-tests:
  context:
  - dockerhub-pulls
@@ -230,7 +230,7 @@ workflows:
  name: Create Release Dry Run
  dryRun: true
  requires:
- - Unit Tests
+ - Build Checks
  # NOTE(mhuynh): Temporarily allow release without these tests passing
  # # Chrome integration tests
  # - Integration Tests chrome beta

CHANGELOG.md

@@ -1,3 +1,18 @@
+2.5.0 (May 9, 2023)
+===================
+
+New Features
+------------
+
+### WebRTC API Overrides (Beta)
+
+The SDK now allows you to override WebRTC APIs using the following options and events. If your environment supports WebRTC redirection, such as [Citrix HDX](https://www.citrix.com/solutions/vdi-and-daas/hdx/what-is-hdx.html)'s WebRTC [redirection technologies](https://www.citrix.com/blogs/2019/01/15/hdx-a-webrtc-manifesto/), your application can use this new *beta* feature for improved audio quality in those environments.
+
+- [Device.Options.enumerateDevices](https://twilio.github.io/twilio-voice.js/interfaces/voice.device.options.html#enumeratedevices)
+- [Device.Options.getUserMedia](https://twilio.github.io/twilio-voice.js/interfaces/voice.device.options.html#getusermedia)
+- [Device.Options.RTCPeerConnection](https://twilio.github.io/twilio-voice.js/interfaces/voice.device.options.html#rtcpeerconnection)
+- [call.on('audio', handler(remoteAudio))](https://twilio.github.io/twilio-voice.js/classes/voice.call.html#audioevent)
+
 2.4.0 (April 6, 2023)
 ===================
 

lib/twilio/audiohelper.ts

@@ -99,6 +99,11 @@ class AudioHelper extends EventEmitter {
  [Device.SoundName.Outgoing]: true,
  };
 
+ /**
+ * The enumerateDevices method to use
+ */
+ private _enumerateDevices: any;
+
  /**
  * The `getUserMedia()` function to use.
  */
@@ -174,9 +179,13 @@ class AudioHelper extends EventEmitter {
  this._getUserMedia = getUserMedia;
  this._mediaDevices = options.mediaDevices || getMediaDevicesInstance();
  this._onActiveInputChanged = onActiveInputChanged;
+ this._enumerateDevices = typeof options.enumerateDevices === 'function'
+ ? options.enumerateDevices
+ : this._mediaDevices && this._mediaDevices.enumerateDevices;
 
  const isAudioContextSupported: boolean = !!(options.AudioContext || options.audioContext);
- const isEnumerationSupported: boolean = !!(this._mediaDevices && this._mediaDevices.enumerateDevices);
+ const isEnumerationSupported: boolean = !!this._enumerateDevices;
+
  const isSetSinkSupported: boolean = typeof options.setSinkId === 'function';
  this.isOutputSelectionSupported = isEnumerationSupported && isSetSinkSupported;
  this.isVolumeSupported = isAudioContextSupported;
@@ -282,7 +291,7 @@ class AudioHelper extends EventEmitter {
  * @private
  */
  _unbind(): void {
- if (!this._mediaDevices) {
+ if (!this._mediaDevices || !this._enumerateDevices) {
  throw new NotSupportedError('Enumeration is not supported');
  }
 
@@ -400,7 +409,7 @@ class AudioHelper extends EventEmitter {
  * Initialize output device enumeration.
  */
  private _initializeEnumeration(): void {
- if (!this._mediaDevices) {
+ if (!this._mediaDevices || !this._enumerateDevices) {
  throw new NotSupportedError('Enumeration is not supported');
  }
 
@@ -526,11 +535,11 @@ class AudioHelper extends EventEmitter {
  * Update the available input and output devices
  */
  private _updateAvailableDevices = (): Promise<void> => {
- if (!this._mediaDevices) {
+ if (!this._mediaDevices || !this._enumerateDevices) {
  return Promise.reject('Enumeration not supported');
  }
 
- return this._mediaDevices.enumerateDevices().then((devices: MediaDeviceInfo[]) => {
+ return this._enumerateDevices().then((devices: MediaDeviceInfo[]) => {
  this._updateDevices(devices.filter((d: MediaDeviceInfo) => d.kind === 'audiooutput'),
  this.availableOutputDevices,
  this._removeLostOutput);
@@ -618,8 +627,13 @@ class AudioHelper extends EventEmitter {
  this._inputVolumeSource.disconnect();
  }
 
- this._inputVolumeSource = this._audioContext.createMediaStreamSource(this._inputStream);
- this._inputVolumeSource.connect(this._inputVolumeAnalyser);
+ try {
+ this._inputVolumeSource = this._audioContext.createMediaStreamSource(this._inputStream);
+ this._inputVolumeSource.connect(this._inputVolumeAnalyser);
+ } catch (ex) {
+ this._log.warn('Unable to update volume source', ex);
+ delete this._inputVolumeSource;
+ }
  }
 
  /**
@@ -696,6 +710,11 @@ namespace AudioHelper {
  */
  audioContext?: AudioContext;
 
+ /**
+ * Overrides the native MediaDevices.enumerateDevices API.
+ */
+ enumerateDevices?: any;
+
  /**
  * A custom MediaDevices instance to use.
  */

lib/twilio/call.ts

@@ -378,6 +378,7 @@ class Call extends EventEmitter {
 
  this._mediaHandler = new (this._options.MediaHandler)
  (config.audioHelper, config.pstream, config.getUserMedia, {
+ RTCPeerConnection: this._options.RTCPeerConnection,
  codecPreferences: this._options.codecPreferences,
  dscp: this._options.dscp,
  forceAggressiveIceNomination: this._options.forceAggressiveIceNomination,
@@ -395,6 +396,11 @@ class Call extends EventEmitter {
  this._latestOutputVolume = outputVolume;
  });
 
+ this._mediaHandler.onaudio = (remoteAudio: typeof Audio) => {
+ this._log.info('Remote audio created');
+ this.emit('audio', remoteAudio);
+ };
+
  this._mediaHandler.onvolume = (inputVolume: number, outputVolume: number,
  internalInputVolume: number, internalOutputVolume: number) => {
  // (rrowland) These values mock the 0 -> 32767 format used by legacy getStats. We should look into
@@ -1510,6 +1516,14 @@ namespace Call {
  */
  declare function acceptEvent(call: Call): void;
 
+ /**
+ * Emitted after the HTMLAudioElement for the remote audio is created.
+ * @param remoteAudio - The HTMLAudioElement.
+ * @example `call.on('audio', handler(remoteAudio))`
+ * @event
+ */
+ declare function audioEvent(remoteAudio: HTMLAudioElement): void;
+
  /**
  * Emitted when the {@link Call} is canceled.
  * @example `call.on('cancel', () => { })`
@@ -1875,6 +1889,11 @@ namespace Call {
  */
  rtcConstraints?: MediaStreamConstraints;
 
+ /**
+ * The RTCPeerConnection passed to {@link Device} on setup.
+ */
+ RTCPeerConnection?: any;
+
  /**
  * Whether the disconnect sound should be played.
  */

lib/twilio/device.ts

@@ -940,7 +940,7 @@ class Device extends EventEmitter {
 
  const config: Call.Config = {
  audioHelper: this._audio,
- getUserMedia,
+ getUserMedia: this._options.getUserMedia || getUserMedia,
  isUnifiedPlanDefault: Device._isUnifiedPlanDefault,
  onIgnore: (): void => {
  this._soundcache.get(Device.SoundName.Incoming).stop();
@@ -952,6 +952,7 @@ class Device extends EventEmitter {
 
  options = Object.assign({
  MediaStream: this._options.MediaStream || rtc.PeerConnection,
+ RTCPeerConnection: this._options.RTCPeerConnection,
  beforeAccept: (currentCall: Call) => {
  if (!this._activeCall || this._activeCall === currentCall) {
  return;
@@ -969,7 +970,7 @@ class Device extends EventEmitter {
  maxAverageBitrate: this._options.maxAverageBitrate,
  preflight: this._options.preflight,
  rtcConstraints: this._options.rtcConstraints,
- shouldPlayDisconnect: () => this.audio?.disconnect(),
+ shouldPlayDisconnect: () => this._audio?.disconnect(),
  twimlParams,
  voiceEventSidGenerator: this._options.voiceEventSidGenerator,
  }, options);
@@ -986,6 +987,12 @@ class Device extends EventEmitter {
 
  const call = new (this._options.Call || Call)(config, options);
 
+ this._publisher.info('settings', 'init', {
+ RTCPeerConnection: !!this._options.RTCPeerConnection,
+ enumerateDevices: !!this._options.enumerateDevices,
+ getUserMedia: !!this._options.getUserMedia,
+ }, call);
+
  call.once('accept', () => {
  this._stream.updatePreferredURI(this._preferredURI);
  this._removeCall(call);
@@ -994,7 +1001,7 @@ class Device extends EventEmitter {
  this._audio._maybeStartPollingVolume();
  }
 
- if (call.direction === Call.CallDirection.Outgoing && this.audio?.outgoing()) {
+ if (call.direction === Call.CallDirection.Outgoing && this._audio?.outgoing()) {
  this._soundcache.get(Device.SoundName.Outgoing).play();
  }
 
@@ -1204,7 +1211,7 @@ class Device extends EventEmitter {
  this._publishNetworkChange();
  });
 
- const play = (this.audio?.incoming() && !wasBusy)
+ const play = (this._audio?.incoming() && !wasBusy)
  ? () => this._soundcache.get(Device.SoundName.Incoming).play()
  : () => Promise.resolve();
 
@@ -1310,8 +1317,11 @@ class Device extends EventEmitter {
  this._audio = new (this._options.AudioHelper || AudioHelper)(
  this._updateSinkIds,
  this._updateInputStream,
- getUserMedia,
- { audioContext: Device.audioContext },
+ this._options.getUserMedia || getUserMedia,
+ {
+ audioContext: Device.audioContext,
+ enumerateDevices: this._options.enumerateDevices,
+ },
  );
 
  this._audio.on('deviceChange', (lostActiveDevices: MediaDeviceInfo[]) => {
@@ -1687,12 +1697,22 @@ namespace Device {
  */
  edge?: string[] | string;
 
+ /**
+ * Overrides the native MediaDevices.enumerateDevices API.
+ */
+ enumerateDevices?: any;
+
  /**
  * Experimental feature.
  * Whether to use ICE Aggressive nomination.
  */
  forceAggressiveIceNomination?: boolean;
 
+ /**
+ * Overrides the native MediaDevices.getUserMedia API.
+ */
+ getUserMedia?: any;
+
  /**
  * Log level.
  */
@@ -1724,6 +1744,46 @@ namespace Device {
  */
  maxCallSignalingTimeoutMs?: number;
 
+ /**
+ * Overrides the native RTCPeerConnection class.
+ *
+ * By default, the SDK will use the `unified-plan` SDP format if the browser supports it.
+ * Unexpected behavior may happen if the `RTCPeerConnection` parameter uses an SDP format
+ * that is different than what the SDK uses.
+ *
+ * For example, if the browser supports `unified-plan` and the `RTCPeerConnection`
+ * parameter uses `plan-b` by default, the SDK will use `unified-plan`
+ * which will cause conflicts with the usage of the `RTCPeerConnection`.
+ *
+ * In order to avoid this issue, you need to explicitly set the SDP format that you want
+ * the SDK to use with the `RTCPeerConnection` via [[Device.ConnectOptions.rtcConfiguration]] for outgoing calls.
+ * Or [[Call.AcceptOptions.rtcConfiguration]] for incoming calls.
+ *
+ * See the example below. Assuming the `RTCPeerConnection` you provided uses `plan-b` by default, the following
+ * code sets the SDP format to `unified-plan` instead.
+ *
+ * ```ts
+ * // Outgoing calls
+ * const call = await device.connect({
+ * rtcConfiguration: {
+ * sdpSemantics: 'unified-plan'
+ * }
+ * // Other options
+ * });
+ *
+ * // Incoming calls
+ * device.on('incoming', call => {
+ * call.accept({
+ * rtcConfiguration: {
+ * sdpSemantics: 'unified-plan'
+ * }
+ * // Other options
+ * });
+ * });
+ * ```
+ */
+ RTCPeerConnection?: any;
+
  /**
  * A mapping of custom sound URLs by sound name.
  */

lib/twilio/log.ts

@@ -54,7 +54,13 @@ class Log {
  * @param [options] - Optional settings
  */
  constructor(options?: LogOptions) {
- this._log = (options && options.LogLevelModule ? options.LogLevelModule : LogLevelModule).getLogger(PACKAGE_NAME);
+ try {
+ this._log = (options && options.LogLevelModule ? options.LogLevelModule : LogLevelModule).getLogger(PACKAGE_NAME);
+ } catch {
+ // tslint:disable-next-line
+ console.warn('Cannot create custom logger');
+ this._log = console as any;
+ }
  }
 
  /**
@@ -93,7 +99,12 @@ class Log {
  * Set a default log level to disable all logging below the given level
  */
  setDefaultLevel(level: LogLevelModule.LogLevelDesc): void {
- this._log.setDefaultLevel(level);
+ if (this._log.setDefaultLevel) {
+ this._log.setDefaultLevel(level);
+ } else {
+ // tslint:disable-next-line
+ console.warn('Logger cannot setDefaultLevel');
+ }
  }
 
  /**