twilio-video 2.23.0 → 2.24.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@ The Twilio Programmable Video SDKs use [Semantic Versioning](http://www.semver.o
 
 **Version 1.x reached End of Life on September 8th, 2021.** See the changelog entry [here](https://www.twilio.com/changelog/end-of-life-complete-for-unsupported-versions-of-the-programmable-video-sdk). Support for the 1.x version ended on December 4th, 2020.
 
+
+2.24.0 (August 22, 2022)
+========================
+
+New Features
+------------
+
+- The support for twilio approved 3rd party noise cancellation solutions is now **generally available**.
+
+Bug Fixes
+---------
+
+- Fixed an issue where input media track was not stopped, after `localAudioTrack.stop()` when using noiseCancellation (VIDEO-11047)
+- Added versioning support for noise cancellation plugin. This SDK will require noise cancellation plugin to be version 1.0.0 or greater. (VIDEO-11087)
+
 2.23.0 (July 28, 2022)
 ======================
 

package/README.md

@@ -74,7 +74,7 @@ Releases of twilio-video.js are hosted on a CDN, and you can include these
 directly in your web app using a <script> tag.
 
 ```html
-<script src="//sdk.twilio.com/js/video/releases/2.23.0/twilio-video.min.js"></script>
+<script src="//sdk.twilio.com/js/video/releases/2.24.0/twilio-video.min.js"></script>
 
 ```
 

package/dist/twilio-video.js

@@ -1,4 +1,4 @@
-/*! twilio-video.js 2.23.0
+/*! twilio-video.js 2.24.0
 
 The following license applies to all parts of this software except as
 documented below.
@@ -3127,6 +3127,9 @@ var LocalAudioTrack = /** @class */ (function (_super) {
      * @fires LocalAudioTrack#stopped
      */
     LocalAudioTrack.prototype.stop = function () {
+        if (this.noiseCancellation) {
+            this.noiseCancellation.stop();
+        }
         return _super.prototype.stop.apply(this, arguments);
     };
     return LocalAudioTrack;
@@ -4711,37 +4714,58 @@ exports.applyNoiseCancellation = exports.NoiseCancellationImpl = void 0;
 var noisecancellationadapter_1 = require("../../noisecancellationadapter");
 var Log = require('../../util/log');
 /**
- * {@link NoiseCancellation} interface provides methods to control noise cancellation at runtime.
- * This interface is exposed on {@link LocalAudioTrack} property `noiseCancellation`. It is available only when
- * {@link NoiseCancellationOptions} are specified when creating a {@link LocalAudioTrack}
+ * {@link NoiseCancellation} interface provides methods to control noise cancellation at runtime. This interface is exposed
+ * on {@link LocalAudioTrack} property `noiseCancellation`. It is available only when {@link NoiseCancellationOptions} are
+ * specified when creating a {@link LocalAudioTrack}, and the plugin is successfully loaded.
  * @alias NoiseCancellation
  * @interface
  *
  * @example
  * const { connect, createLocalAudioTrack } = require('twilio-video');
  *
- * // create a local audio track and have it use
- * // @twilio/krisp-audio-plugin for noise cancellation processing.
- * const localAudioTrack = await Video.createLocalAudioTrack({
+ * // Create a LocalAudioTrack with Krisp noise cancellation enabled.
+ * const localAudioTrack = await createLocalAudioTrack({
  *   noiseCancellationOptions: {
- *     vendor: 'krisp',
- *     sdkAssetsPath: '/twilio-krisp-audio-plugin/1.0.0/dist'
+ *     sdkAssetsPath: 'path/to/hosted/twilio/krisp/audio/plugin/1.0.0/dist',
+ *     vendor: 'krisp'
  *   }
  * });
  *
- * // publish the track to a room
- * const room = await connect( token, {
- *   tracks: [localAudioTrack]
- *   // ... any other connect options
- * });
+ * if (!localAudioTrack.noiseCancellation) {
+ *   // If the Krisp audio plugin fails to load, then a warning message will be logged
+ *   // in the browser console, and the "noiseCancellation" property will be set to null.
+ *   // You can still use the LocalAudioTrack to join a Room. However, it will use the
+ *   // browser's noise suppression instead of the Krisp noise cancellation. Make sure
+ *   // the "sdkAssetsPath" provided in "noiseCancellationOptions" points to the correct
+ *   // hosted path of the plugin assets.
+ * } else {
+ *   // Join a Room with the LocalAudioTrack.
+ *   const room = await connect('token', {
+ *     name: 'my-cool-room',
+ *     tracks: [localAudioTrack]
+ *   });
  *
- * // you can enable/disable noise cancellation at runtime
- * // using noiseCancellation interface exposed by localAudioTrack
- * function updateNoiseCancellation(enable: boolean) {
- *   const noiseCancellation = localAudioTrack.noiseCancellation;
+ *   if (!localAudioTrack.noiseCancellation.isEnabled) {
+ *     // Krisp noise cancellation is permanently disabled in Peer-to-Peer and Go Rooms.
+ *   }
+ * }
  *
+ * //
+ * // Enable/disable noise cancellation.
+ * // @param {boolean} enable - whether noise cancellation should be enabled
+ * //
+ * function setNoiseCancellation(enable) {
+ *   const { noiseCancellation } = localAudioTrack;
  *   if (noiseCancellation) {
- *     enable ? noiseCancellation.enable() : noiseCancellation.disable();
+ *     if (enable) {
+ *       // If enabled, then the LocalAudioTrack will use the Krisp noise
+ *       // cancellation instead of the browser's noise suppression.
+ *       noiseCancellation.enable();
+ *     } else {
+ *       // If disabled, then the LocalAudioTrack will use the browser's
+ *       // noise suppression instead of the Krisp noise cancellation.
+ *       noiseCancellation.disable();
+ *     }
  *   }
  * }
  */
@@ -4753,7 +4777,7 @@ var NoiseCancellationImpl = /** @class */ (function () {
     }
     Object.defineProperty(NoiseCancellationImpl.prototype, "vendor", {
         /**
-         * Identifies the vendor
+         * Name of the noise cancellation vendor.
          * @type {NoiseCancellationVendor}
          */
         get: function () {
@@ -4764,7 +4788,7 @@ var NoiseCancellationImpl = /** @class */ (function () {
     });
     Object.defineProperty(NoiseCancellationImpl.prototype, "sourceTrack", {
         /**
-         * Underlying MediaStreamTrack
+         * The underlying MediaStreamTrack of the {@link LocalAudioTrack}.
          * @type {MediaStreamTrack}
          */
         get: function () {
@@ -4775,7 +4799,7 @@ var NoiseCancellationImpl = /** @class */ (function () {
     });
     Object.defineProperty(NoiseCancellationImpl.prototype, "isEnabled", {
         /**
-         * Set to true if noise cancellation is currently enabled
+         * Whether noise cancellation is enabled.
          * @type {boolean}
          */
         get: function () {
@@ -4785,8 +4809,10 @@ var NoiseCancellationImpl = /** @class */ (function () {
         configurable: true
     });
     /**
-     * Enables noise cancellation
-     * @returns {Promise<void>} a promise that resolves when operation is complete.
+     * Enable noise cancellation.
+     * @returns {Promise<void>} Promise that resolves when the operation is complete
+     * @throws {Error} Throws an error if noise cancellation is disabled permanently
+     *   for the {@link LocalAudioTrack}
      */
     NoiseCancellationImpl.prototype.enable = function () {
         if (this._disabledPermanent) {
@@ -4796,8 +4822,8 @@ var NoiseCancellationImpl = /** @class */ (function () {
         return Promise.resolve();
     };
     /**
-     * Disables noise cancellation
-     * @returns {Promise<void>} a promise that resolves when operation is complete.
+     * Disable noise cancellation.
+     * @returns {Promise<void>} Promise that resolves when the operation is complete
      */
     NoiseCancellationImpl.prototype.disable = function () {
         this._processor.disable();
@@ -4839,6 +4865,13 @@ var NoiseCancellationImpl = /** @class */ (function () {
         this._disabledPermanent = true;
         return this.disable();
     };
+    /**
+     * @private
+     */
+    NoiseCancellationImpl.prototype.stop = function () {
+        this._processor.disconnect();
+        this._sourceTrack.stop();
+    };
     return NoiseCancellationImpl;
 }());
 exports.NoiseCancellationImpl = NoiseCancellationImpl;
@@ -7433,29 +7466,57 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createNoiseCancellationAudioProcessor = void 0;
 var Log = require('./util/log');
 var dynamicImport = require('./dynamicImport');
-var KRISP_PLUGIN_FILE = 'krispsdk.mjs';
-var RNNOISE_PLUGIN_FILE = 'rnnoise_sdk.mjs';
+var PLUGIN_CONFIG = {
+    krisp: {
+        supportedVersion: '1.0.0',
+        pluginFile: 'krispsdk.mjs'
+    },
+    rnnoise: {
+        supportedVersion: '0.6.0',
+        pluginFile: 'rnnoise_sdk.mjs'
+    }
+};
+var ensureVersionSupported = function (_a) {
+    var supportedVersion = _a.supportedVersion, plugin = _a.plugin, log = _a.log;
+    if (!plugin.getVersion || !plugin.isSupported) {
+        throw new Error('Plugin does not export getVersion/isSupported api. Are you using old version of the plugin ?');
+    }
+    var pluginVersion = plugin.getVersion();
+    log.debug("Plugin Version = " + pluginVersion);
+    var supportedVersions = supportedVersion.split('.').map(function (version) { return Number(version); });
+    var pluginVersions = pluginVersion.split('.').map(function (version) { return Number(version); });
+    if (supportedVersions.length !== 3 || pluginVersions.length !== 3) {
+        throw new Error("Unsupported Plugin version format: " + supportedVersion + ", " + pluginVersion);
+    }
+    if (supportedVersions[0] !== pluginVersions[0]) {
+        throw new Error("Major version mismatch: [Plugin version " + pluginVersion + "],  [Supported Version " + supportedVersion + "]");
+    }
+    if (pluginVersions[1] < supportedVersions[1]) {
+        throw new Error("Minor version mismatch: [Plugin version " + pluginVersion + "] < [Supported Version " + supportedVersion + "]");
+    }
+    var tempContext = new AudioContext();
+    var isSupported = plugin.isSupported(tempContext);
+    tempContext.close();
+    if (!isSupported) {
+        throw new Error('Noise Cancellation plugin is not supported on your browser');
+    }
+};
 var audioProcessors = new Map();
 function createNoiseCancellationAudioProcessor(noiseCancellationOptions, log) {
     return __awaiter(this, void 0, void 0, function () {
-        var audioProcessor, sdkFilePath, rootDir, dynamicModule, plugin_1, er_1;
+        var audioProcessor, pluginConfig, supportedVersion, pluginFile, rootDir, sdkFilePath, dynamicModule, plugin_1, er_1;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
                     audioProcessor = audioProcessors.get(noiseCancellationOptions.vendor);
                     if (!!audioProcessor) return [3 /*break*/, 6];
-                    sdkFilePath = void 0;
-                    rootDir = noiseCancellationOptions.sdkAssetsPath;
-                    switch (noiseCancellationOptions.vendor) {
-                        case 'krisp':
-                            sdkFilePath = rootDir + "/" + KRISP_PLUGIN_FILE;
-                            break;
-                        case 'rnnoise':
-                            sdkFilePath = rootDir + "/" + RNNOISE_PLUGIN_FILE;
-                            break;
-                        default:
-                            throw new Error("Unsupported NoiseCancellationOptions.vendor: " + noiseCancellationOptions.vendor);
+                    pluginConfig = PLUGIN_CONFIG[noiseCancellationOptions.vendor];
+                    if (!pluginConfig) {
+                        throw new Error("Unsupported NoiseCancellationOptions.vendor: " + noiseCancellationOptions.vendor);
                     }
+                    supportedVersion = pluginConfig.supportedVersion, pluginFile = pluginConfig.pluginFile;
+                    rootDir = noiseCancellationOptions.sdkAssetsPath;
+                    sdkFilePath = rootDir + "/" + pluginFile;
                     _a.label = 1;
                 case 1:
                     _a.trys.push([1, 5, , 6]);
@@ -7465,6 +7526,11 @@ function createNoiseCancellationAudioProcessor(noiseCancellationOptions, log) {
                     dynamicModule = _a.sent();
                     log.debug('Loaded noise cancellation sdk:', dynamicModule);
                     plugin_1 = dynamicModule.default;
+                    ensureVersionSupported({
+                        supportedVersion: supportedVersion,
+                        plugin: plugin_1,
+                        log: log
+                    });
                     if (!!plugin_1.isInitialized()) return [3 /*break*/, 4];
                     log.debug('initializing noise cancellation sdk: ', rootDir);
                     return [4 /*yield*/, plugin_1.init({ rootDir: rootDir })];
@@ -29461,7 +29527,7 @@ module.exports={
   "name": "twilio-video",
   "title": "Twilio Video",
   "description": "Twilio Video JavaScript Library",
-  "version": "2.23.0",
+  "version": "2.24.0",
   "homepage": "https://twilio.com",
   "author": "Mark Andrus Roberts <mroberts@twilio.com>",
   "contributors": [