twilio-video 2.18.0 → 2.19.0

package/CHANGELOG.md

@@ -2,6 +2,72 @@ 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.19.0 (January 31, 2022)
+=========================
+
+New Features
+------------
+
+- This release introduces a new feature **Adaptive Simulcast**. This opt-in feature can be enabled by setting `preferredVideoCodecs="auto"` in ConnectOptions. When joining a group room with this feature enabled, the SDK will use VP8 simulcast, and will enable/disable simulcast layers dynamically, thus improving bandwidth and CPU usage for the publishing client. It works best when used along with `Client Track Switch Off Control` and `Video Content Preferences`. These two flags allow the SFU to determine which simulcast layers are needed, thus allowing it to disable the layers not needed on publisher side. This feature cannot be used alongside `maxVideoBitrate`.
+
+If your application is currently using VP8 simulcast we recommend that you switch to this option.
+
+Example:
+
+```ts
+const { connect } = require('twilio-video');
+
+const room = await connect(token, {
+  preferredVideoCodecs: 'auto',
+  bandwidthProfile: {
+    video: {
+      contentPreferencesMode: 'auto',
+      clientTrackSwitchOffControl: 'auto'
+    }
+  }
+});
+```
+
+Known Limitations
+-----------------
+
+- Specifying `preferredVideoCodecs="auto"` will revert to unicast in the following cases:
+  - The publisher is using Firefox.
+  - The publisher has preferred the H264 codec.
+  - The Room is configured to support only the H264 codec.
+  - Peer-to-Peer Rooms
+- When the participant is being recorded, the SFU will not disable any simulcast layers of the participant's VideoTrack.
+
+Bug Fixes
+---------
+
+- Fixed a bug where `clientTrackSwitchOffControl` and `contentPreferencesMode` sometimes did not work as expected during network glitches. (VIDEO-7654)
+
+2.18.3 (January 4, 2022)
+========================
+
+Bug Fixes
+---------
+
+- Fixed a bug where connect was returning a Promise type instead of a CancelablePromise. (VIDEO-7831)
+- Fixed a bug where `audioLevel`, `frameRate`, and `captureDimensions` WebRTC stats are returning null on certain browsers. With this release, these stats are now populated whenever they are available. (VIDEO-3600)
+
+2.18.2 (December 15, 2021)
+==========================
+
+Bug Fixes
+---------
+
+- Fixed a bug where setting `clientTrackSwitchOffControl` to `auto` caused the RemoteVideoTracks to get switched off while playing in picture-in-picture mode. Note that this fix does not apply to Firefox as it does not yet implement [picture-in-picture](https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API) APIs. (VIDEO-6677)
+
+2.18.1 (October 29, 2021)
+=========================
+
+Changes
+-------
+
+- Added some metrics to track the usage of the **Preflight API Public Beta** (`runPreflight`). There are no changes to the public APIs in this release. (VIDEO-6891)
+
 2.18.0 (October 13, 2021)
 =========================
 

package/COMMON_ISSUES.md

@@ -36,6 +36,13 @@ before opening a new issue. We recommend regularly upgrading to the latest versi
 
 ### Chrome mobile
 <details>
+<summary>Android 12: Video distortion on Chrome when hardware acceleration is enabled</summary>
+<p>
+
+   This is a VP8 encoder issue on Android 12. Please see this [github ticket](https://github.com/twilio/twilio-video.js/issues/1627) and this [Chrome bug](https://bugs.chromium.org/p/chromium/issues/detail?id=1237677) for more details.
+</p>
+</details>
+<details>
 <summary>Android Chrome on Pixel 3 receives corrupted video frames with codec VP8</summary>
 <p>
 
@@ -54,6 +61,13 @@ before opening a new issue. We recommend regularly upgrading to the latest versi
 
 ### Safari desktop
 <details>
+<summary>Browser crashes when muting a VideoTrack that is using an H264 codec on Safari 15.1</summary>
+<p>
+
+   Due to a regression on Safari 15.1, the browser crashes when a VideoTrack is muted that is using an H264 codec. Please use VP8 as a workaround for now. See more details [here](https://github.com/twilio/twilio-video.js/issues/1611).
+</p>
+</details>
+<details>
 <summary>Failures to publish tracks on Safari 15</summary>
 <p>
 
@@ -99,14 +113,107 @@ before opening a new issue. We recommend regularly upgrading to the latest versi
 
 ### Safari mobile
 <details>
+<summary>iOS 15: VideoTracks goes black and the page freezes on certain interruptions</summary>
+<p>
+
+   Certain interruptions such as incoming calls, backgrounding the browser or switching between apps causes VideoTracks on Chrome and Safari on iOS 15.1 to go black. Sometimes, the whole page also freezes and become unresponsive causing audio and video to cut off. These issues are regressions on iOS 15.1. See the following bugs for more details.
+
+   * [Page freezing](https://bugs.webkit.org/show_bug.cgi?id=230922#c12)
+   * [VideoTrack going black](https://bugs.webkit.org/show_bug.cgi?id=232599)
+
+   A workaround can be implemented to prevent the VideoTrack from going black. This workaround however doesn't prevent the issue where sometimes the page freezes. It is recommended to apply this workaround on Chrome and Safari on iOS 15.1.
+
+  ```js
+  // Keeps track of video elements and their event listeners
+  const videoElements = {};
+
+  // Listen to onPlay and onPause events and intelligently re-attach the video element
+  function shimVideoElement(track, el) {
+    let wasInterrupted = false;
+
+    const onPause = () => {
+      wasInterrupted = true;
+    };
+
+    const onPlay = () => {
+      if (wasInterrupted) {
+        track.detach(el);
+        track.attach(el);
+        wasInterrupted = false;
+      }
+    };
+
+    el.addEventListener('pause', onPause);
+    el.addEventListener('play', onPlay);
+
+    // Track this element so we can remove the listeners
+    videoElements[el] = { onPause, onPlay };
+  }
+  ```
+
+  Apply the workaround after attaching the video element.
+
+  ```js
+  videoTrack.attach(videoElement);
+  shimVideoElement(videoTrack, videoElement);
+  ```
+
+  Remove the listeners before detaching the video element.
+
+  ```js
+  const { onPause, onPlay } = videoElements[videoElement];
+  videoElement.removeEventListener('pause', onPause);
+  videoElement.removeEventListener('play', onPlay);
+  ```
+</p>
+</details>
+<details>
+<summary>iOS 15: Browser crashes when publishing or muting a VideoTrack that is using an H264 codec</summary>
+<p>
+
+   Chrome and Safari on iOS 15.1 crashes when a VideoTrack is muted or published using an H264 codec. This issue happens due to a regression on iOS 15.1. Please use VP8 as a workaround for now. See more details [here](https://github.com/twilio/twilio-video.js/issues/1611).
+</p>
+</details>
+<details>
 <summary>iOS 15: Low audio volume in Safari</summary>
 <p>
-   Safari on iOS version 15, sometimes routes audio to the earpiece and not the speakers by default. Which customers some time perceive as low audio volume. Find more details [here](https://github.com/twilio/twilio-video.js/issues/1586) and in this [WebKit bug](https://bugs.webkit.org/show_bug.cgi?id=230902).
+
+   Safari on iOS version 15, sometimes routes audio to the earpiece and not the speakers by default. Which customers some time perceive as low audio volume. Find more details [here](https://github.com/twilio/twilio-video.js/issues/1586) and in this [WebKit bug](https://bugs.webkit.org/show_bug.cgi?id=230902). As a workaround, you can pipe all remote audio tracks into a single audio context for iOS 15. Using a gain node, you can increase the gain value to increase the audio volume levels. See example below.
+
+   ```js
+   // Make sure to reuse the audioContext object as browsers
+   // have limits to the number of AudioContext instances you can create.
+   const audioContext = new (window.AudioContext || window.webkitAudioContext)();
+
+   function attachAudioTrack(remoteAudioTrack) {
+     const audioNode = audioContext.createMediaStreamSource(new MediaStream([remoteAudioTrack.mediaStreamTrack]));
+     const gainNode = audioContext.createGain();
+     
+     // Adjust this value depending on your customers' preference
+     gainNode.gain.value = 20;
+     
+     audioNode.connect(gainNode);
+     gainNode.connect(audioContext.destination);
+   }
+
+   // Attach the RemoteAudioTrack once received.
+   attachAudioTrack(remoteAudioTrack);
+   ```
+
+   This workaround has the following potential side effects.
+
+   * There is a possibility of the introduction of echo. Please adjust the gain value and check for echo while testing the workaround.
+   * The output volume might end up really high if the user switches headsets.
+   * The default volume might end up really high once Apple rolls out the fix for this issue.
+
+   Keeping the side effects in mind, you might need to adjust your UI to improve the experience. For example, you can turn off this workaround by default and have a "call to action" in your UI that allows the user to turn the volume up if they cannot hear any audio. This button will then apply the workaround. Another option is to listen for `devicechange` events to determine if the user switches headsets. When this happens, you will have the ability to reset the gain value.
+
 </p>
 </details>
 <details>
 <summary>iOS 15: Audio is lost in a video call after an interruption with a phone call</summary>
 <p>
+
    Due to a regression on Safari on iOS 15, an incoming call causes local and sometimes remote media playback to stop. You can find more details in this [WebKit bug](https://bugs.webkit.org/show_bug.cgi?id=230537).
 </p>
 </details>

package/LICENSE.md

@@ -1,7 +1,7 @@
 The following license applies to all parts of this software except as
 documented below.
 
-    Copyright (C) 2019-2021 Twilio, inc.
+    Copyright (C) 2019-2022 Twilio, inc.
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without

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.18.0/twilio-video.min.js"></script>
+<script src="//sdk.twilio.com/js/video/releases/2.19.0/twilio-video.min.js"></script>
 
 ```