Known Issues and Workarounds

Impact: All browsers and apps that use WKWebView on iOS 15.1.x, such as Safari and Chrome.

Details: If you set codec as 'h264' when calling createClient, the browsers on iOS 15.1.x crash after you send the video stream.

Reason: This issue happens due to the regression of the WebKit video encoder on iOS 15.1.x. For details, see WebKit Bug 231505.

Workaround: Use the VP8 codec for video encoding.

createClient({codec:'vp8', mode})

Impact: Safari on iOS 15.x

Reason: The issue occurs because WebRTC H264 LowLatency encoder is enabled by default for Safari on iOS 15.x. For details, see Webkit bug 238366.

Workaround: The following workarounds are available:

• Use the VP8 codec for video encoding. The sample code is as follows:

  createClient({codec:'vp8', mode})

• On the iOS device, go to Settings > Safari > Advanced > Experimental Features, and disable WebRTC H264 LowLatency encoder.

Impact: All browsers and apps that use WKWebView on iOS 15.0 to 15.3, such as Safari and Chrome.

Details: On iOS 15.0 to 15.3, after the local user subscribes to the RemoteAudioTrack and plays it, sometimes the audio is routed to the earpiece instead of the speaker, and the volume that the local user hear may be very low.

Reason: This issue happens due to the regression of the WebKit audio module on iOS 15.0 to 15.3. For details, see WebKit Bug 230902.

Workaround: On iOS 15.0 to 15.3, use WebAudio to play the audio, and use GainNode to increase the audio volume level. Use the following workaround:

1. Upgrade to the Web SDK 4.9.0 or later versions.

2. Set the SDK private parameter REMOTE_AUDIO_TRACK_USES_WEB_AUDIO as true. The SDK uses WebAudio to play the remote audio stream. Sample code:

   function isIOS15(ua){
       // Use UA to judge whether the iOS version is 15
   }
   
   if(isIOS15(navigator.userAgent)){
       // If you are using Typescript, add the "@ts-ignore" tag before calling setParameter
       // @ts-ignore
       AgoraRTC.setParameter("REMOTE_AUDIO_TRACK_USES_WEB_AUDIO", true);
   }

Impact: All browsers and apps that use WKWebView on iOS 15.x, such as Safari and Chrome.

Details: On iOS 15.x, if you play the video in DOM node and add some CSS properties (such as transform and animation) to thevideo element or its parent element, or if you change the CSS properties to redraw the video rendering area, sometimes the video goes black.

Reason: This issue happens due to the regression of the WebKit video renderer on iOS 15.x. For details, see WebKit Bug 230902.

Workaround: Upgrade to the Web SDK v4.7.3 or later and minimize changes to the CSS properties of the video element and its parent elements.

Impact: All browsers and apps that use WKWebView on iOS 15.x, such as Safari and Chrome.

Reason: This issue happens due to the regression of the WebKit audio playback module on iOS 15.x. For details, see WebKit Bug 231422.

Workaround: Agora recommends that you add a prompt to remind users of possible audio distortion issues when they use a Bluetooth headset.

Impact:

• Safari on iOS 15.x.
• Browsers and apps that use WKWebView (such as Chrome) on iOS 14.4 to iOS 15.x.

Reason:

• For Safari: This happens primarily due to this WebKit bug. After the browser switches to the background, the AudioContext of WebAudio stops processing audio.
• For browsers and apps using WKWebView: This happens because iOS WKWebView prohibits microphone usage while in the background. For details, see Microphone gets muted in background.

Workaround: Currently there is no workaround for browsers and apps using WKWebView. For Safari on iOS 15.x, you can follow these steps to avoid this issue:

1. Upgrade to the Web SDK v4.7.3 or later versions.

2. When calling createMicrophoneAudioTrack, set bypassWebAudio as true. The Web SDK directly publishes the local audio stream without processing it through WebAudio.

   const localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack({bypassWebAudio: true});

   Note that this workaround has a side effect. After applying this workaround, the audio mixing function (MixingAudioTrack) in the SDK fails.

Impact: All browsers and apps that use WKWebView on iOS 15.x, such as Safari and Chrome.

Reason: Such interruptions can cause the state of the video and audio elements to be paused. After the interruption finishes, the state cannot be automatically switched back to playing, and even calling HTMLMediaElement.play cannot resume the media playback. See the WebKit bug 232599 and 226698 for more details.

Workaround: Upgrade to the Web SDK v4.7.3 or later versions. The SDK attempts to resume media playback after the interruption. Agora recommends that you add a prompt that instructs users to refresh the page.

• The volume of a remote user can change randomly on iOS 13 and 14.
• Switching between the front and rear cameras can momentarily rotate the video.
• The audio routing can change randomly. Sometimes, the audio is routed to the speakerphone when a headset is connected or to the earpiece when no headset is connected.
• If you call getUserMedia twice to get two tracks of the same media type, the first track goes muted or black.
• After a user switches to another app that uses the microphone or camera (such as Siri or Skype) and then switches back, the audio sampling or video capture fails.

Reason: iOS Safari and WKWebView do not support the mediaDevices.getDisplayMedia method.

Reason: WebGL is not well supported on iOS Safari and WKWebView, and the image enhancement algorithm can reduce the system performance below acceptable levels.

Reason: WebAudio on iOS does not support this method.

Reason: The Web SDK uses the H.264 Baseline Profile for negotiation, so encoding and sending a video stream with a resolution of 1080p or higher is not supported on iOS.

Reason: iOS Safari and WkWebView do not support setting the frame rate with the RTCRTPSender.setParameters method. After compressing the resolution with the scaleResolutionDownBy property, the resolution of the low-quality stream stays proportional to the resolution of the high-quality stream.

Reason: The encodeDelay property cannot be calculated through the getStats method of WebRTC on iOS.

Reason: iOS AVCaptureSession prohibits camera usage while in the background. For details, see AVCaptureSessionInterruptionReason or Chromium issue 4294.

Reason: iOS and iOS WebView do not support setting the volume of a media object through the HTMLMediaElement.volume property.

Impact: The Chrome browser or Chromium kernel browser 97 or earlier on certain devices with Android 12, such as Pixel 3 and Pixel 4.

Details: If the Chrome browser on Android 12 enables the WebRTC H264 or VP8 hardware acceleration by default, video distortion can occur.

Reason: This issue happens due to the regression of the Chromium WebRTC video encoder. For details, see Chromium issue 1237677.

Workaround: Chrome 97 fixed this issue. You can instruct users to upgrade to Chrome 97 or later versions.

Scope: Certain Android devices, such as Xiaomi and OnePlus.

Reason: This is a hardware encoder issue. The bitrate fails to reach the preset value at a specific video encoding frame rate.

Workaround: In most cases, the bitrate is relatively lower when the frame rate is set as 15 fps. If you set the frame rate as 30 fps, the bitrate increases. So Agora recommends trying to set the frame rate as 30 fps when encountering a bitrate issue. However, setting the frame rate as fps may cause performance issues.

Impact: The WeChat browser using Chromium 89 kernel

Details: The autoplay of inaudible media is blocked. Even after the user interacts with the webpage to resume the video playback, the autoplay block is still not removed.

Reason: This issue happens because the WeChat browser implements a custom autoplay policy.

Workaround: Follow these steps to avoid this issue:

1. Upgrade to the Web SDK v4.6.0 or later versions.

2. Listen to the AgoraRTC.onAutoplayFailed event. Instruct the user to click on the page to resume playback:

   AgoraRTC.onAutoplayFailed = ()=>{
       document.alert('Please click the page to resume playback');
   }

Scope: Certain Xiaomi and OnePlus devices

Details: If a local user wears a Bluetooth headset, when the Bluetooth headset starts capturing the audio, there is a possibility that the remote audio is lost.

Reason: It may be due to the audio issue on Chromium regarding the profile switch of the Bluetooth.

Workaround: Agora recommends that you add a prompt to remind users of possible audio-loss issues when they use a Bluetooth headset.

Scope: Chromium-based browsers on Android devices

Details: When a local users is sending audio, if the user switches from using the speaker to using a Bluetooth headset, the remote audio still comes from the speaker.

Reason: The audio routing on Android devices is controlled by the Android operating system and cannot be fixed at Chromium's level. For details, see Chromium issue 1317548。

• On devices equipped with MediaTek chips, the Web SDK cannot encode and send video streams in H.264.
• On devices equipped with Huawei HiSilicon Kirin chips, if you use Chrome versions earlier than 88, the Web SDK cannot encode and send video streams in H.264.
• When receiving video streams on Chrome on OnePlus 6, if the screen turns off, the video can freeze.
• Harmony OS does not support sending the video stream of 180p.

• On some Android devices, the device labels might not be available.
• On some Android devices, tracks can end if the audio and video streams are interrupted by system phone calls or other audio or video calling apps. To resume the call, the Web SDK needs to re-capture the audio and video.
• On Android Chrome, the Web SDK cannot send high-quality and low-quality streams in H.264.
• On Android Chrome earlier than 90, the volume obtained by getVolumeLevel is 0, but the user can hear the audio.
• On Android system Webview versions from 55 to 75, the decodeFrameRate property stays 0.

Reason: The mediaDevices.getDisplayMedia method is not implemented on mobile browsers and WkWebView.

Reason: The image enhancement algorithm can reduce the system performance of mobile devices below acceptable levels.