Web SDK 已知问题和规避方案

影响范围：运行 iOS 16 系统的所有 iPhone 14 系列手机。

问题原因：iPhone 14 系列手机上 WebKit 的 WebAudio 相关功能有回退，导致 WebAudio 启用后音频采集相关功能异常。详见 WebKit Bug 246019。

规避方案：使用 LocalAudioTrack.setMuted 代替 LocalAudioTrack.setEnabled 来控制本地音频的采集和发送，并且不要调用 LocalAudioTrack.close 关闭本地轨道。

影响范围：iOS 16.0 上的所有浏览器和内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

问题原因：iOS 16.0 上 WebKit 的 WebRTC 模块功能有回退，对 RTP 协议的图像方向（Coordination of video orientation, CVO）功能支持异常，导致手机旋转后画面被拉伸。

规避方案：建议在业务层面添加提示。

影响范围：iOS 15.1.x 上的所有浏览器和内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

问题描述：iOS 15.1.x 上如果你调用 createClient 时将 codec 设为 'h264'，发送视频流后，页面会崩溃。

问题原因：该问题是由 iOS 15.1.x 上 WebKit 视频编码功能回退导致，详见 WebKit Bug 231505。

规避方案：使用 VP8 进行视频编码。

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

影响范围：iOS 15.x 上的 Safari 浏览器。

问题原因：该问题是由 iOS 15.x 上的 Safari 默认开启 WebRTC H264 LowLatency encoder 导致，详见 Webkit bug 238366。

规避方案：可以通过以下方案规避：

• 使用 VP8 进行视频编码，示例代码如下：

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

• 在 iOS 设备上前往设置 > Safari 浏览器 > 高级 > Experimental Features，关闭 WebRTC H264 LowLatency encoder。

影响范围：iOS 15.0 至 15.3 上的所有浏览器及内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

问题描述：iOS 15.0 至 15.3 上订阅并播放远端音频轨道 RemoteAudioTrack 后，播放音量有概率极低，且音频从听筒中而不是扬声器中播放出来。

问题原因：该问题是由 iOS 15.0 至 15.3 上 WebKit 音频功能回退导致，详见 WebKit Bug 230902。

规避方案：iOS 15.0 至 15.3 上使用 WebAudio 进行音频播放并使用 GainNode 调整音量后，可以提高播放音量。声网建议你按照以下步骤规避该问题：

1. 升级至 Web SDK 4.9.0 或以上版本。

2. 设置 SDK 私有参数 REMOTE_AUDIO_TRACK_USES_WEB_AUDIO 为 true。SDK 内部会使用 WebAudio 播放远端音频流。示例代码如下：

   function isIOS15(ua){
       // 通过 UA 判断 iOS 版本是否为 15
   }
   
   if(isIOS15(navigator.userAgent)){
       // Typescript 开发者在调用 setParameter 前需要加上 ”@ts-ignore“ 标签，JavaScript 不需要。
       // @ts-ignore
       AgoraRTC.setParameter("REMOTE_AUDIO_TRACK_USES_WEB_AUDIO", true);
   }

影响范围：iOS 15.x 和 16.x 上的所有浏览器及内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

问题描述：iOS 15.x 和 16.x 上在 DOM 中播放视频且在 video 元素或其父元素添加某些 CSS 属性（如 transform、animation）后，或者改变 CSS 属性重绘视频渲染区域后，有概率视频播放出现黑屏。

问题原因：该问题是由 iOS 15.x 和 16.x 上 WebKit 视频渲染功能回退导致，详见 WebKit Bug 230532。

规避方案：升级至 Web SDK 4.7.3 或以上版本，并且尽量减少更改 video 元素及其父元素的 CSS 属性。

影响范围：iOS 15.x 上的所有浏览器及内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

问题原因：该问题是由 iOS 15.x 上 WebKit 音频播放功能回退导致，详见 WebKit Bug 231422。

规避方案：声网建议你在业务层面添加提示，告知用户使用蓝牙耳机可能出现音频失真问题。

影响范围：iOS 15.x 上的 Safari 浏览器；iOS 14.4 至 15.x 上内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

问题原因：

• Safari 浏览器：由于 WebKit 的 bug，浏览器切换至后台后，WebAudio 的 AudioContext 会停止音频处理。
• 内嵌 WKWebView 的应用：iOS WKWebView 不允许在后台使用麦克风，详见苹果论坛说明 Microphone gets muted in background 。

规避方案：内嵌 WKWebView 的应用暂时无法规避此问题。iOS 15.x 上的 Safari 浏览器可以参考以下步骤规避此问题：

1. 升级至 Web SDK 4.7.3 或之后版本。

2. 调用 createMicrophoneAudioTrack 创建音频轨道时，将bypassWebAudio 参数设为 true，本地音频流会不经由 WebAudio 处理直接发布。

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

   注意：此方案会导致混音功能（MixingAudioTrack）失效。

影响范围：iOS 15.x 上的所有浏览器及内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

问题原因：音视频播放被打断后，DOM video 元素和 audio 元素的状态变为 paused。打断结束后，状态无法自动切回 playing，且调用HTMLMediaElement.play 方法也无法恢复媒体的播放。详见 WebKit bug 232599 和WebKit bug 226698。

规避方案：升级至 Web SDK 4.7.3 或以上版本。SDK 会尝试在打断事件后恢复媒体播放。声网建议你在业务层面增加提示，引导用户刷新页面。

• iOS 13 和 14 上可能出现远端用户音量随机变化的问题。
• 切换前置、后置摄像头后采集画面可能会瞬间旋转。
• 语音路由随机切换，即可能出现插着耳机但是仍然从扬声器出声，或者没有耳机却从听筒出声的情况。
• 连续两次调用 getUserMedia 获取相同媒体类型的轨道，第一次获取的媒体轨道会静音或黑屏。
• 使用过其他使用音视频输入设备的 app 后（例如 Siri 或者 Skype 通话），无法采集本地音频或视频。

原因：iOS Safari 及 WKWebView 不支持 mediaDevices.getDisplayMedia 接口。

原因：iOS Safari 及 WKWebView 对 WebGL 支持不佳，且 iOS 设备在进行美颜算法处理时性能消耗过大。

原因：iOS 上 WebAudio 不支持实现该方法。

原因：Web SDK 使用 H.264 Baseline Profile 进行协商，因此 iOS 上不支持编码发送 1080p 及以上分辨率的视频流。

原因：iOS Safari 及 WKWebView 中 RTCRTPSender.setParameters 方法无法指定帧率，通过 scaleResolutionDownBy 属性进行分辨率压缩后，小流分辨率与大流成固定比率。

原因：iOS 上无法通过 WebRTC 的 getStats 接口计算出 encodeDelay。

原因： iOS AVCaptureSession 不允许在后台使用摄像头。详见苹果官方说明 AVCaptureSessionInterruptionReason 和 Chromium issue 4294。

原因：iOS 以及 iOS 上的 WebView 不支持通过设置 HTMLMediaElement.volume 属性改变音量。

影响范围：部分安装了 Android 12 的设备，如 Pixel 3 和 Pixel 4，且使用 Chrome 浏览器或 Chromium 内核浏览器 97 或以下版本。

问题描述：在 Android 12 上使用 Chrome 浏览器或 Chromium 内核浏览器 97 或以下版本，如果默认开启 WebRTC H264 或 VP8 视频硬件编码，可能会导致花屏。

问题原因：该问题是由 Chromium WebRTC 模块视频编码回退导致，详见 Chromium issue 1237677。

规避方案：Chrome 97 已修复该问题，建议用户升级至 Chrome 97 或以上版本。

影响范围：部分 Android 设备，如部分小米及 One Plus 机型。

问题原因：可能是因为硬件编码导致特定视频编码帧率下码率无法达到预设值。

规避方案：大部分情况下，视频编码帧率为 15 fps 时，码率会过低，而帧率为 30 fps 时码率则相对较高。因此声网建议遇到码率问题时，尝试将帧率设为 30 fps。请注意，将帧率设为 30 fps 可能会带来性能问题。

影响范围：大部分 Android 设备。

规避方案：先调用 close 或 setEnable(false) 释放已有的视频轨道，再创建新的视频轨道。

影响范围：使用 Chromium 89 内核的微信浏览器。

问题描述：微信浏览器中视频无法自动播放。并且当用户通过手势（点击、触摸）恢复播放后，下一次视频仍然无法自动播放。

问题原因：可能是微信浏览器对自动播放的行为处理有异常，与其他浏览器的行为不一致。

规避方案：参考以下步骤规避此问题：

1. 升级至 Web SDK 4.6.0 或以上版本。

2. 监听 AgoraRTC.onAutoplayFailed 事件。在此事件中，引导用户点击页面，恢复播放：

    AgoraRTC.onAutoplayFailed = ()=>{
        document.alert('请点击页面后恢复播放');
    }

影响范围：部分小米及 One Plus 机型

问题描述：如果本地用户佩戴蓝牙耳机，在通话过程中通过蓝牙耳机采集本地音频且发送音频流后，有概率会无法收听到远端用户的声音。

问题原因：可能是由于 Chromium 在蓝牙设备的 profile 切换后会产生音频异常。

规避方案：声网建议你在业务层面添加提示，告知用户使用蓝牙耳机可能出现无声问题。

影响范围：Android 设备上使用 Chromium 为内核的浏览器

问题描述：本地用户在发送音频流时，如果从扬声器切换到蓝牙耳机，远端用户的音频仍然通过扬声器播放。

问题原因：Android 设备的音频路由全部由 Android 操作系统分配，Chromium 不能修改。详见 Chromium issue 1317548。

• 在搭载联发科芯片的设备上无法使用 H.264 编码在 Chrome 浏览器中发送视频流。
• 在搭载华为海思麒麟芯片的设备上，Android Chrome 88 以下版本上，无法使用 H.264 编码发送视频流。
• 在 OnePlus 6上使用 Chrome 浏览器接收远端视频流期间熄灭屏幕，可能会导致视频流冻结。
• 鸿蒙系统不支持发 180p 的视频流。

• 在部分 Android 设备上可能无法获取到媒体设备的 device label。
• 在部分 Android 设备上音视频流被系统电话呼叫或其他语音和视频通话应用打断，可能会导致 track-ended，需要重新采集音视频。
• Android Chrome 上无法使用 H.264 编码发送大小流。
• Android Chrome 90 以下版本中 getVolumeLevel 获取到的音量为 0，但是能听到声音。
• Android 系统 WebView 55 至 75 版本中 decodeFrameRate 为 0。

原因：移动端浏览器及 WKWebView 未实现 mediaDevices.getDisplayMedia 接口。

原因：移动端设备在进行美颜算法处理时性能消耗过大。