twilio-video 2.24.0 → 3.0.0-preview.3

package/CHANGELOG.md

@@ -1,66 +1,142 @@
-The Twilio Programmable Video SDKs use [Semantic Versioning](http://www.semver.org/). Twilio supports version N-1 for 12 months after the first GA release of version N. We recommend you upgrade to the latest version as soon as possible to avoid any breaking changes. Version 2.x is the lastest Video JavaScript SDK.
+The Twilio Programmable Video SDKs use [Semantic Versioning](http://www.semver.org/). Twilio supports version N-1 for 12 months after the first GA release of version N. We recommend you upgrade to the latest version as soon as possible to avoid any breaking changes. Version 2.x is the latest Video JavaScript SDK.
 
 **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.
 
+3.0.0-preview.3 (August 31, 2022)
+=================================
 
-2.24.0 (August 22, 2022)
-========================
-
-New Features
-------------
+Breaking Changes
+----------------
 
-- The support for twilio approved 3rd party noise cancellation solutions is now **generally available**.
+- The LocalTrack constructors that do not require the `new` operator have been removed. Please use the es6 classes that
+  are exported in the `Video` namespace. (VIDEO-10893)
+- The deprecated ConnectOptions property `dscpTagging` has been removed. Use `enableDscp` instead. (VIDEO-10893)
+- The deprecated ConnectOptions property `eventListener` has been removed. You can listen for the signaling events by
+  intercepting the Logger's messages as shown [here](#2100-december-10-2020). (VIDEO-10893)
+- The deprecated ConnectOptions properties `abortOnIceServersTimeout` and `iceServersTimeout` have been removed. (VIDEO-10893)
+- The deprecated VideoBandwidthProfile properties `maxTracks` and `renderDimensions` have been removed. (VIDEO-10893)
+- Fixed the RemoteAudioTrack and RemoteVideoTrack property `mediaStreamTrack`'s type, which is supposed to be
+  `MediaStreamTrack | null`. (VIDEO-10893)
+- The `id` property has been removed from the LocalTrack classes. Use the `name` property instead. (VIDEO-10893)
+- The `trackId` and `ssrc` properties have been removed from the TrackStats class. (VIDEO-10893)
+- The `maxAudioBitrate` and `maxVideoBitrate` properties in ConnectOptions and EncodingParameters now accept values
+  in **kiliobits per second (kbps)**, as opposed to bits per second (bps) earlier. (VIDEO-10893)
+- The `maxSubscriptionBitrate` property in VideoBandwidthProfile now accepts values in **kiliobits per second (kbps)**,
+  as opposed to bits per second (bps) earlier. (VIDEO-10893)
+- The deprecated ConnectOptions property `logLevel` has been removed. Use the `Video.Logger` interface instead as shown
+  [here](#2100-december-10-2020). (VIDEO-10893)
 
 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)
+- Fixed a bug where sometimes `Room.getStats()` returned statistics for unsubscribed RemoteTracks. (VIDEO-11199)
+- Fixed a bug where sometimes the SDK generated a TypeError in the browser console. (VIDEO-11203)
 
-2.23.0 (July 28, 2022)
-======================
+3.0.0-preview.2 (August 18, 2022)
+=================================
+
+Changes
+-------
+
+- `Room.getStats()`, which was broken in `3.0.0-preview.1`, has been fixed in this release. Note that the values reported
+  are best-effort approximations based off of the raw WebRTC statistics. (VIDEO-8756)
+
+3.0.0-preview.1 (July 25, 2022)
+===============================
 
 New Features
 ------------
 
-- This release adds private beta support for 3rd party noise cancellation solution. You need to host twilio approved 3rd party plugin on your web server to enable noise cancellation. Please fill out [this form](https://forms.gle/eeFyoGJj1mgMrxN88) to request access to the 3rd party plugin.
-
-Once you get the access to the plugin, You can install it from npm with:
-```
-npm install <noise_cancellation_plugin>
-```
+**Large Rooms Pilot**
+
+twilio-video.js now allows you to create and join a [Large Group Room](https://www.twilio.com/docs/video/large-group-rooms),
+which supports a large number of Participants (> 50). This feature is in pilot, and requires that your account be enabled
+in order to use it. **Note that the following API changes apply only for Large Rooms, and not for non-large Group Rooms and
+Peer-to-Peer Rooms**.
+
+- An audio and video RemoteTrack will now have an additional property called `switchOffReason`, which describes the
+  [reason](https://sdk.stage.twilio.com/js/video/releases/3.0.0-preview.1/docs/global.html#TrackSwitchOffReason) for
+  it being switched off. The `switchedOff` event will also have this reason string as a second argument. (VIDEO-8670, VIDEO-8748)
+- An audio or video RemoteTrack's `mediaStreamTrack` is set to `null` whenever it is switched off. When it is switched
+  on, it is set to a MediaStreamTrack. (VIDEO-8668, VIDEO-8745)
+- When the `switchOffReason` changes for an already switched off audio or video RemoteTrack, the `switchedOff` event is
+  raised. (VIDEO-8668, VIDEO-8745)
+- A RemoteAudioTrack of a Participant that is not active in the Large Room will now be switched off. (VIDEO-8668)
+- A RemoteVideoTrack will now be switched off if the number of switched on RemoteVideoTracks reached the limit set by the media server. (VIDEO-8745)
+- Renamed BandwidthProfileOptions to BandwidthProfile. (VIDEO-8754)
+- Renamed VideoBandwidthProfileOptions to VideoBandwidthProfile. (VIDEO-8753)
+- The `isEnabled` property of the RemoteTrack is deprecated and scheduled for removal. Alternatively, you can determine if
+  a RemoteTrack is enabled by using the following expression. (VIDEO-8742, VIDEO-8750)
+  ```js
+  const isEnabled = remoteTrack.switchOffReason !== 'disabled-by-publisher';
+  ```
+- The `disabled` and `enabled` events of the RemoteTrack are deprecated and scheduled for removal. Alternatively, you can
+  handle the `switchedOff` and `switchedOn` events as shown below. (VIDEO-8742, VIDEO-8750)
+  ```js
+  let recentSwitchOffReason = remoteTrack.switchOffReason;
 
-Once installed, you need to host the contents of `./node_modules/<noise_cancellation_plugin>/dist/` from your web server. We recommend that you add plugin version number to the hosted path to ensure that browser does not use [stale version](https://www.keycdn.com/support/what-is-cache-busting) when its updated. You need to pass the path to the hosted files to `twilio-video` sdk when creating audio track as shown in the example below. The example below assumes that you have hosted the files at `/noise_cancellation_plugin/1.0.0/dist` on your web server.
+  remoteTrack.on('switchedOff', switchOffReason => {
+    recentSwitchOffReason = switchOffReason;
+    if (switchOffReason === 'disabled-by-publisher') {
+      /* The RemoteTrack is disabled. */
+    }
+  });
 
-```ts
-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({
-  noiseCancellationOptions: {
-    vendor: 'krisp',
-    sdkAssetsPath: '/noise_cancellation_plugin/1.0.0/dist'
-  }
-});
+  remoteTrack.on('switchedOn', () => {
+    if (recentSwitchOffReason === 'disabled-by-publisher') {
+      /* The RemoteTrack is enabled. */
+    }
+    recentSwitchOffReason = null;
+  });
+  ```
+- The `isTrackEnabled` property of the RemoteTrackPublication is deprecated and scheduled for removal. Alternatively, you
+  can determine if a RemoteTrackPublication is enabled by using the following expression. (VIDEO-8743, VIDEO-8751)
+  ```js
+  const { track } = remoteTrackPublication;
+  const isTrackEnabled = !(track && track.switchOffReason === 'disabled-by-publisher');
+  ```
+  `isTrackEnabled` is now only valid for RemoteTracks that are subscribed to, and defaults to `true` for unsubscribed
+  RemoteTracks.
+- The `trackDisabled` and `trackEnabled` events of the RemoteTrack are deprecated and scheduled for removal. Alternatively,
+  you can handle the `trackSwitchedOff` and `trackSwitchedOn` events as shown below. (VIDEO-8743, VIDEO-8751)
+  ```js
+  const { track } = remoteTrackPublication;
+  let recentSwitchOffReason = track ? track.switchOffReason : null;
 
-// publish the track to a room
-const room = await connect( token, {
-  tracks: [localAudioTrack]
-  // ... any other connect options
-});
+  remoteTrackPublication.on('trackSwitchedOff', (track, switchOffReason) => {
+    recentSwitchOffReason = switchOffReason;
+    if (switchOffReason === 'disabled-by-publisher') {
+      /* The RemoteTrack is disabled. */
+    }
+  });
 
-// you can enable/disable noise cancellation at runtime
-// using noiseCancellation interface exposed by localAudioTrack
-function updateNoiseCancellation(enable: boolean) {
-  const noiseCancellation = localAudioTrack.noiseCancellation;
+  remoteTrackPublication.on('trackSwitchedOn', (track) => {
+    if (recentSwitchOffReason === 'disabled-by-publisher') {
+      /* The RemoteTrack is enabled. */
+    }
+    recentSwitchOffReason = null;
+  });
+  ```
+  The `trackDisabled` and `trackEnabled` events are now only fired for subscribed RemoteTracks.
+- Any audio and video Tracks shared while joining the Room will **no longer** be guaranteed to be published by the time
+  the CancelablePromise returned by `connect()` is resolved. The application will now have to listen to the "trackPublished"
+  event on the LocalParticipant. (VIDEO-8817)
+  ```js
+  const room = await connect('token', {
+    audio: true,
+    video: true,
+    room: 'my-large-room'
+  });
 
-  if (noiseCancellation) {
-    enable ? noiseCancellation.enable() : noiseCancellation.disable();
-  }
-}
+  room.localParticipant.on('trackPublished', publication => {
+    console.log(`Successfully published ${publication.kind} Track`);
+  });
+  ```
+- `Room.getStats()` is broken, and will be fixed in an upcoming release. For now, the Track-level stats returned by this
+  method will not be accurate.
+- [PSTN Participants](https://www.twilio.com/docs/video/adding-programmable-voice-participants-video-rooms) cannot connect
+  to Large Rooms.
 
-```
 2.22.2 (July 25, 2022)
 ======================
 
@@ -68,7 +144,7 @@ Changes
 -------
 
 - `isSupported` flag now returns `false` if the browser does not support the Unified Plan SDP format. (VIDEO-10307)
-
+  
   The following is a list of browsers with Unified Plan as the default SDP format.
   - Chrome 72+
   - Safari 12.1+

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.24.0/twilio-video.min.js"></script>
+<script src="//sdk.twilio.com/js/video/releases/3.0.0-preview.3/twilio-video.min.js"></script>
 
 ```