# 浏览器兼容性和已知问题 (/zh-CN/realtime-media/rtc/reference/browser-compatibility) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" /> 声网 Web SDK 是一款基于 WebRTC 技术的实时音视频 SDK,因此 WebRTC 技术的浏览器兼容性决定了声网 Web SDK 的浏览器兼容性。本文介绍声网 Web SDK 支持在哪些浏览器中使用。 ## 桌面端 [#桌面端] Web SDK 在桌面端的 Chrome、Firefox、Safari、Edge 等浏览器上的支持度较好。为保证最佳的用户体验,声网建议在最新版本的操作系统中使用上述浏览器的最新版本: - 下载 [Chrome 官方最新版本](https://www.google.com/intl/zh-CN/chrome/)。 - 下载 [Firefox 官方最新版本](https://www.mozilla.org/firefox/new/)。 - 下载 [Edge 官方最新版本](https://microsoft.com/edge)。 - 下载 [Safari 官方最新版本](https://support.apple.com/en-hk/HT201541)。 ### 兼容性 [#兼容性] 下文列出了浏览器的最低版本要求。为获得更好的体验,声网推荐你使用最新版本的浏览器。 macOS Windows ChromeOS | 浏览器 | 浏览器版本要求 | 接收音视频流 | 发布音视频流 | 屏幕共享 | | :--------------------------- | --------------- | :----------- | :----------- | -------- | | Chrome | 65 或以上版本 | ✔ | ✔ | ✔ | | Firefox | 69 或以上版本 | ✔ | ✔ | ✔ | | Safari | 11 或以上版本 | ✔ | ✔ | ✔ (需要 Safari 13 或以上版本) | | Edge | 无明确信息 | ✔ | ✔ | ✔ | | 浏览器 | 浏览器版本要求 | 接收音视频流 | 发布音视频流 | 屏幕共享 | | :--------------------------- | --------------- | :----------- | :----------- | -------- | | Chrome | 65 或以上版本 | ✔ | ✔ | ✔ | | Firefox | 69 或以上版本 | ✔ | ✔ | ✔ | | Edge | 80 或以上版本 | ✔ | ✔ | ✔ | | 浏览器 | 浏览器版本要求 | 接收音视频流 | 发布音视频流 | 屏幕共享 | | :----------------- | --------------- | :--- | :--- | -------- | | Chrome | 89 或以上版本 | ✔ | ✔ | ✔ | ### 已知问题和限制 [#已知问题和限制] 由于各平台和应用内置浏览器的实现方式各不相同,导致支持的 Web SDK 功能也可能有所不同,因此会存在已知问题和已知限制: - 已知问题:由特定浏览器版本的 Bug 所造成的问题。针对已知问题,声网提供规避方案。 - 已知限制:由于浏览器自身存在问题,Web SDK 无法支持的 API 或功能。 - 在 Windows 系统上,Chrome 122 及以上版本使用 Web SDK 进行窗口屏幕共享时,若切换到全屏幻灯片放映模式,屏幕共享的画面在接收端会停留在非全屏状态,无法显示全屏后的幻灯片页面。 解决方案:重新分享整个屏幕而非特定窗口。 - 从 Chrome 117 起,Web SDK 4.9.3 及以下版本中不再支持 `getStats()` 方法,调用该方法时返回值全部为 0。 问题原因:旧版 `getStats()` WebRTC API 将从 Chrome 117 中移除,详见 [Chrome 官方说明](https://developer.chrome.com/blog/getstats-migration)。 解决方案:升级到更高版本的 Web SDK。 - 在所有使用 AMD 芯片和部分使用 Intel 芯片的 Windows 设备上,Chrome 使用 H.264 编码时,发送码率可能达不到设定值。 解决方案:使用 VP8 编码或者尝试关闭硬件加速。 - macOS 上 Chrome 84 存在缺陷,采用 H.264 格式进行编码时, WebRTC 有概率出现帧率突然下降导致图像卡顿。详见 Google 官方说明 [Issue 1088650](https://bugs.chromium.org/p/chromium/issues/detail?id=1203206&can=2&q=webrtc%20drop%20component%3ABlink%3EWebRTC%3EVideo) 和 [Issue 12704](https://bugs.chromium.org/p/webrtc/issues/detail?id=12704#c3)。 解决方案:建议你在 macOS 上 Chrome 84 及以后版本中使用 VP8 ,直至 Google 修复该缺陷。 - 特定场景下 Chrome 的回声消除 (AEC) 失效。 问题原因:如果对接收的远端音频流进行了额外处理(比如空间音频),AEC 无法获取到参考信号,详见 Chrome 官方说明 [Issue 687574](https://bugs.chromium.org/p/chromium/issues/detail?id=687574)。 解决方案:建议用户戴上耳机,避免使用扬声器。如果需要使用扬声器,请[联系技术支持](https://ticket.shengwang.cn/)。 - 在部分 Windows 设备上选择音频采集设备为立体声混音,远端用户将听不到声音。 解决方案:建议避免选择立体声混音作为音频采集设备。 - 在 Windows 设备上使用 `deviceId` 为 `"default"` 或 `"communications"` 的麦克风时,如果插入新的麦克风再拔出,原麦克风的采集可能中断。 解决方案:建议避免使用 `deviceId` 为 `"default"` 或 `"communications"` 的麦克风。 - 在 macOS Ventura 的 Safari 16.2 和 16.3 上通过 `createScreenVideoTrack` 创建屏幕共享视频轨道后,调用 `setEncoderConfiguration` 修改该轨道的视频分辨率时可能会出现绿屏。 问题原因:WebKit 的功能回退,详见 [Bug 254652](https://bugs.webkit.org/show_bug.cgi?id=254652)。 解决方案: 升级至 macOS Ventura 13.3、Safari 16.4 版本。 - Safari 16.1 上调用 `createScreenVideoTrack` 方法时,如果在 `encoderConfig` 中传入自定义的视频编码配置,该方法会调用失败。 问题原因:WebKit 的屏幕共享功能有回退,详见 [Bug 247310](https://bugs.webkit.org/show_bug.cgi?id=247310)。 解决方案:在 `encoderConfig` 中通过 `ScreenEncoderConfigurationPreset` 传入 SDK 内置的编码配置。调用示例: ```Javascript AgoraRTC.createScreenVideoTrack({encoderConfig:'720p_1'}) ``` - Safari 17.2 上使用 Web SDK 存在无法正常切换到小流的问题。 - Safari 17 上调用 `getDisplayMedia` 时,对屏幕共享视频流的约束设置不生效,导致视频模糊。 - Safari 15.4 及以上版本如果将本地音频轨道的采样率设为 32000 Hz,本地音频轨道会终止(即触发 `LocalAudioTrack.on('track-ended')` 事件)。 - Safari 15.1 上使用 H.264 编码时,[MediaStreamTrack.enabled](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/enabled) 设为 `false` 会导致页面崩溃。 - Safari 14.0.1 和 14.2 上音频可能断断续续。 - Safari 13 的用户可能听不到远端用户的声音。 - Safari 12.1 及之前版本仅支持 H.264 编解码。 - Safari 11 只支持 480P 及以上分辨率。 - 在 Safari 上切换到其它标签页后,新订阅的远端音频流不会自动播放,需要切回 SDK 所在的标签页才开始播放。 - Safari 无法获取输出设备信息,因此不支持 `getPlayoutDevices` 和 `setAudioOutput` 这两个方法。 - Safari 上如果调用 `setAudioFrameCallback` 添加了原始音频数据回调,调用 `setAudioFrameCallback(null)` 后 Safari 的音频图标不会消失。原因是 Safari 的 [ScriptProcessorNode](https://developer.mozilla.org/zh-CN/docs/Web/API/ScriptProcessorNode#%E6%96%B9%E6%B3%95) 对象调用 `disconnect` 方法有问题。 - Safari 上调用相关方法获取质量相关统计数据时,多个字段的值为 0。例如调用 `getLocalAudioStats` 获取本地音频轨道的质量相关信息时,`sendPacketsLost` 字段值为 0。 - 在部分使用 Intel 芯片的 Mac 设备的 Safari 浏览器上,调用 `enableDualStream` 开启 H.264 编码的视频双流模式时,小流与大流分辨率比率低于 1/4 可能会导致系统卡顿。 - 如果 Safari 没有打开**自动播放**(如下图所示),直接播放音视频流会听不到声音,必须在播放前调用 `navigator.mediaDevices.getUserMedia` 方法获取设备权限。 ![img](https://web-cdn.agora.io/docs-files/1591078696865) - Firefox 138 版本接收端黑屏问题 问题描述:用户在使用 Firefox 138 浏览器进行实时音视频互动时,接收端可能出现视频黑屏现象。 问题原因:这个问题是由 Firefox 浏览器自身版本回退导致。Firefox 138 版本进行了临时性调整,导致视频流解码失败。此问题属于浏览器厂商的兼容性变更,详见:https://bugzilla.mozilla.org/show_bug.cgi?id=1965831 。 规避方案:声网目前已经通过配置下发临时处理该问题。对于一些无痕模式的用户,配置下发可能无效,需要修改集成。建议你[联系技术支持](https://ticket.shengwang.cn)。 - 使用 Windows 设备在 Firefox 98 版本上发送 H.264 视频流时,接收端无法在订阅后立即收到关键帧,导致出图时间变慢。 - Firefox 上使用 Web SDK 时与某些设备互通时,Firefox 端看其他端的视频画面会发生旋转。 - Firefox 只支持视频帧率设为 30 fps。 - Firefox 上不支持设置音频编码码率。 - 在部分设备上 Firefox 设置视频编码配置不生效,目前已知有此问题的设备如下: - MacBook Pro (13-inch, 2016, Two Thunderbolt 3 ports) - Windows 10 (MI) - 在使用 Apple M1 芯片的 Mac 设备上 Firefox 不支持 H.264 编解码,详见 [Firefox 官方说明](https://bugzilla.mozilla.org/show_bug.cgi?id=1686470)。 - Firefox 上不支持获取 `codecType`、`sendFrameRate` 和 `captureFrameRate`。 - Firefox 上 Web SDK 最低视频码率的默认设置不生效。 - Firefox 上不支持 H.264 视频流的 SEI 信息发送功能。 - Chrome 81 及以上版本、Safari 和 Firefox 浏览器需要在获得媒体设备权限后才能获取设备 ID,详见[为什么在 Chrome 81 浏览器上无法获取设备 ID?](/zh-CN/realtime-media/rtc/reference/browser-compatibility)该限制影响 `getMicrophones`、`getCameras`、`getPlaybackDevices` 方法。 - `setPlaybackDevice` 方法仅支持 Chrome 浏览器,其他浏览器调用将会抛出 `NOT_SUPPORTED` 错误。 - `setOptimizationMode` 方法以及 `CameraVideoTrackInitConfig`、`ScreenVideoTrackInitConfig` 和 `CustomVideoTrackInitConfig` 类中的 `optimizationMode` 字段仅支持 Chrome 浏览器。 - 调用 `createScreenVideoTrack` 开启屏幕共享有以下限制: - Chrome 要求 58 或以上版本。如果 Chrome < 72,需要先安装声网提供的 Chrome 屏幕共享插件并获取插件的 `extensionId`,在创建轨道时填入 `extensionId`。如果 Chrome ≥ 72,则直接调用 `createScreenVideoTrack`。 - Firefox 要求 56 或以上版本。Firefox 在 Windows 平台不支持 `application` 模式。 - Windows 10+ 平台上的 Edge 要求 80 及以上版本。 - Safari 要求 13 或以上版本。在 Safari 上屏幕共享默认共享整个显示器屏幕,不可选择共享哪些内容。 - 共享音频功能(`createScreenVideoTrack` 中的 `withAudio` 参数)仅支持 Chrome 74 及以上版本。Windows 平台支持在共享整个屏幕和共享 Chrome 标签页时分享音频,不支持在共享应用窗口时分享音频。macOS 平台仅支持在共享 Chrome 标签页时分享音频。 ## 移动端 [#移动端] :::info[信息] 自 4.6.0 起,Web SDK 优化了在移动端浏览器上的体验。如果你想提升在移动端的体验,声网强烈建议你升级到 4.x 最新版本。 ::: ### 兼容性 [#兼容性-1] 下文列出的版本为浏览器的最低版本要求。 Android iOS HarmonyOS Android 支持自研 WebView 或引入第三方 WebView,不同设备、不同应用的 WebView 可能实现不同,因此对 Web SDK 的支持与应用版本和设备硬件有关。 | 浏览器 | 浏览器版本要求 | 接收音视频流 | 发布音视频流 | 屏幕共享 | | :---------------------------------------- | ------------------- | :--- | :--- | -------- | | Chrome | 78 或以上版本 | ✔ | ✔ | ✘ | | 微信内置浏览器 | 微信 7.0.20 或以上版本 | ✔ | ✔ | ✘ | | 企业微信内置浏览器 | 企业微信 3.1.6 或以上版本 | ✔ | ✔ | ✘ | iOS 只支持系统 WebView,因此对 Web SDK 的支持只与 iOS 系统版本有关。 **iOS 版本 ≥ 12.2 且 < 14.3** | 浏览器 | 浏览器版本要求 | 接收音视频流 | 发布音视频流 | 屏幕共享 | | :----------------- | ------------------- | :--- | :--- | -------- | | Safari | 与 iOS 系统版本对应 | ✔ | ✔ | ✘ | | Chrome | 无明确信息 | ✔ | ✘ | ✘ | | 微信内置浏览器 | 微信 8.0.13 或以上版本 | ✔ | ✘ | ✘ | | 企业微信内置浏览器 | 企业微信 3.1.15 或以上版本① | ✔ | ✘ | ✘ | **iOS 版本 ≥ 14.3** | 浏览器 | 浏览器版本要求 | 接收音视频流 | 发布音视频流 | 屏幕共享 | | :----------------- | ------------------- | :--- | :--- | -------- | | Safari | 与 iOS 系统版本对应 | ✔ | ✔ | ✘ | | Chrome | 92 或以上版本 | ✔ | ✔ | ✘ | | 微信内置浏览器 | 微信 8.0.13 或以上版本 | ✔ | ✔ | ✘ | | 企业微信内置浏览器 | 企业微信 3.1.15 或以上版本① | ✔ | ✔ | ✘ | :::info[信息] ① 在企业微信内直接打开链接无法互通。需要开启麦克风和相机权限后,重启企业微信,打开链接刷新页面才能正常互通。 ::: 目前仅 Mate 60 Pro 机型支持升级至 HarmonyOS NEXT 5.0 或以上版本的鸿蒙系统,你需要在该类设备上使用华为浏览器,才能使用 Web SDK 接收和发布视频流。 | 浏览器 | 浏览器版本要求 | 接收音视频流 | 发布音视频流 | 屏幕共享 | | :---------------------------------------- | ------------------- | :--- | :--- | -------- | | 华为浏览器 | 无明确信息 | ✔ | ✔ | ✘ | ### 已知问题和限制 [#已知问题和限制-1] 由于各平台和应用内置浏览器的实现方式各不相同,导致支持的 Web SDK 功能也可能有所不同,因此会存在已知问题和已知限制: - 已知问题:由 iOS/Android/HarmonyOS 平台特定浏览器/机型的 Bug 所造成的问题。针对已知问题,声网提供规避方案。 - 已知限制:由于 iOS/Android/HarmonyOS 平台的问题,Web SDK 无法支持的 API 或功能。 #### 已知问题 [#已知问题] Android iOS HarmonyOS **影响范围**:部分安装了 Android 12 的设备,如 Pixel 3 和 Pixel 4,且使用 Chrome 浏览器或 Chromium 内核浏览器 97 或以下版本。 **问题描述**:在 Android 12 上使用 Chrome 浏览器或 Chromium 内核浏览器 97 或以下版本,如果默认开启 WebRTC `H264` 或 `VP8` 视频硬件编码,可能会导致花屏。 **问题原因**:该问题是由 Chromium WebRTC 模块视频编码回退导致,详见 [Chromium issue 1237677](https://bugs.chromium.org/p/chromium/issues/detail?id=1237677)。 **规避方案**:Chrome 97 已修复该问题,建议用户升级至 Chrome 97 或以上版本。 **影响范围**:Android Chrome 119.0.6045.67 版本。 **问题描述**:用户 A 使用该版本的 Android Chrome 加入频道,用户 B 使用其它浏览器加入频道,如果用户 A 不佩戴耳机,用户 B 会听到自己的回声。 **问题原因**:该问题由 [Chromium issue](https://bugs.chromium.org/p/chromium/issues/detail?id=1501352) 导致。 **规避方案**:Android Chrome 119 最新版本已修复该问题,建议用户升级至 119.0.6045.134 或以上版本。 **影响范围**:部分 Android 设备,如部分小米及 One Plus 机型。 **问题原因**:可能是因为硬件编码导致特定视频编码帧率下码率无法达到预设值。 **规避方案**:大部分情况下,视频编码帧率为 15 fps 时,码率会过低,而帧率为 30 fps 时码率则相对较高。因此声网建议遇到码率问题时,尝试将帧率设为 30 fps。请注意,将帧率设为 30 fps 可能会带来性能问题。 **问题描述**:Android Chrome 上调用 `createCameraVideoTrack` 创建两个参数不同的视频轨道,浏览器报错 `NotReadableError: Could not start video source`。 **影响范围**:大部分 Android 设备。 **规避方案**:先调用 `close` 或 `setEnable(false)` 释放已有的视频轨道,再创建新的视频轨道。 **影响范围**:使用 Chromium 89 内核的微信浏览器。 **问题描述**:微信浏览器中视频无法自动播放。并且当用户通过手势(点击、触摸)恢复播放后,下一次视频仍然无法自动播放。 **问题原因**:可能是微信浏览器对自动播放的行为处理有异常,与其他浏览器的行为不一致。 **规避方案**:参考以下步骤规避此问题: 1. 升级至 Web SDK 4.6.0 或以上版本。 2. 监听 `AgoraRTC.onAutoplayFailed` 事件。在此事件中,引导用户点击页面,恢复播放: ```javascript AgoraRTC.onAutoplayFailed = ()=>{ document.alert('请点击页面后恢复播放'); } ``` **影响范围**:部分小米及 One Plus 机型。 **问题描述**:如果本地用户佩戴蓝牙耳机,在通话过程中通过蓝牙耳机采集本地音频且发送音频流后,有概率会无法收听到远端用户的声音。 **问题原因**:可能是由于 Chromium 在蓝牙设备协议 (Bluetooth Profile) 切换后会产生音频异常。 **规避方案**:声网建议你在业务层面添加提示,告知用户使用蓝牙耳机可能出现无声问题。 **影响范围**:Android 设备上使用 Chromium 为内核的浏览器。 **问题描述**:本地用户在发送音频流时,如果从扬声器切换到蓝牙耳机,远端用户的音频仍然通过扬声器播放。 **问题原因**:Android 设备的音频路由全部由 Android 操作系统分配,Chromium 不能修改。详见 [Chromium issue 1317548](https://bugs.chromium.org/p/chromium/issues/detail?id=1317548&q=bluetooth&can=2)。 - 在搭载**联发科芯片**的设备上无法使用 H.264 编码在 Chrome 浏览器中发送视频流。 - 在搭载**华为海思麒麟芯片**的设备上,Android Chrome 88 以下版本上,无法使用 H.264 编码发送视频流。 - 在 **OnePlus 6**上使用 Chrome 浏览器接收远端视频流期间熄灭屏幕,可能会导致视频流冻结。 - **鸿蒙系统**不支持发 180p 的视频流。 - 在部分 OPPO 机型(如 Reno4 和 A11)上运行 Android 11 系统时,由于不支持 WebRTC,导致出现黑屏和无声现象。 **影响范围**:运行 iOS 16 系统的所有 iPhone 14 系列手机。 **问题原因**:iPhone 14 系列手机上 WebKit 的 WebAudio 相关功能有回退,导致 WebAudio 启用后音频采集相关功能异常。详见 [WebKit Bug 246019](https://bugs.webkit.org/show_bug.cgi?id=246019)。 **规避方案**:使用 `LocalAudioTrack.setMuted` 代替 `LocalAudioTrack.setEnabled` 来控制本地音频的采集和发送,并且不要调用 `LocalAudioTrack.close` 关闭本地轨道。 **影响范围**:安装 iOS 15.x 和 16.x 系统的 iPad 和 iPhone 特定机型上的 Chrome 和 Safari 浏览器。特定机型包括: - iPad (5th Gen) - iPad (6th Gen) - iPad (7th Gen) - iPad Pro (1st Gen) - iPhone SE (1st Gen) **规避方案**:升级到最新 iOS 版本。 **影响范围**: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](https://bugs.webkit.org/show_bug.cgi?id=231505)。 **规避方案**:使用 VP8 进行视频编码。 ```javascript createClient({codec:'vp8', mode}) ``` **影响范围**:iOS 15.x 上的 Safari 浏览器。 **问题原因**:该问题是由 iOS 15.x 上的 Safari 默认开启 **WebRTC H264 LowLatency encoder** 导致,详见 [Webkit bug 238366](https://bugs.webkit.org/show_bug.cgi?id=238366)。 **规避方案**:可以通过以下方案规避: - 使用 VP8 进行视频编码,示例代码如下: ```javascript 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](https://bugs.webkit.org/show_bug.cgi?id=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` 播放远端音频流。示例代码如下: ```javascript 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](https://bugs.webkit.org/show_bug.cgi?id=230532)。 **规避方案**:升级至 Web SDK 4.7.3 或以上版本,并且尽量减少更改 `video` 元素及其父元素的 CSS 属性。 **影响范围**:iOS 15.x 上的所有浏览器及内嵌 WKWebView 的应用(如微信浏览器和 Chrome 浏览器)。 **问题原因**:该问题是由 iOS 15.x 上 WebKit 音频播放功能回退导致,详见 [WebKit Bug 231422](https://bugs.webkit.org/show_bug.cgi?id=231422)。 **规避方案**:声网建议你在业务层面添加提示,告知用户使用蓝牙耳机可能出现音频失真问题。 **影响范围**:iOS 15.x 上的 Safari 浏览器;iOS 14.4 至 15.x 上内嵌 WKWebView 的应用(如微信浏览器和 Chrome 浏览器)。 **问题原因**: - Safari 浏览器:由于 WebKit 的 [bug](https://bugs.webkit.org/show_bug.cgi?id=231105),浏览器切换至后台后,`WebAudio` 的 `AudioContext` 会停止音频处理。 - 内嵌 WKWebView 的应用:iOS `WKWebView` 不允许在后台使用麦克风,详见苹果论坛说明 [Microphone gets muted in background](https://developer.apple.com/forums/thread/689182)。 **规避方案**:内嵌 WKWebView 的应用暂时无法规避此问题。iOS 15.x 上的 Safari 浏览器可以参考以下步骤规避此问题: 1. 升级至 Web SDK 4.7.3 或之后版本。 2. 调用 `createMicrophoneAudioTrack` 创建音频轨道时,将 `bypassWebAudio` 参数设为 `true`,本地音频流会不经由 `WebAudio` 处理直接发布。请注意此方案会导致混音功能 (`MixingAudioTrack`) 失效。 ```javascript const localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack({bypassWebAudio: true}); ``` **影响范围**:iOS 15.x 上的所有浏览器及内嵌 WKWebView 的应用(如微信浏览器和 Chrome 浏览器)。 **问题原因**:音视频播放被打断后,DOM `video` 元素和 `audio` 元素的状态变为 `paused`。打断结束后,状态无法自动切回 `playing`,且调用 `HTMLMediaElement.play` 方法也无法恢复媒体的播放。详见 [WebKit bug 232599](https://bugs.webkit.org/show_bug.cgi?id=232599) 和 [WebKit bug 226698](https://bugs.webkit.org/show_bug.cgi?id=226698)。 **规避方案**:参考以下方案: - 方案一:升级至 Web SDK 4.7.3 或以上版本。SDK 会尝试在打断事件后恢复媒体播放。声网建议你在业务层面增加提示,引导用户刷新页面。 - 方案二:升级至 Web SDK 4.20.0 或以上版本。SDK 会抛出打断事件通知,并且提供 `resumeAudioContext` 方法用于恢复媒体播放。详见 [API 文档](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#resumeaudiocontext)。 - iOS 13 和 14 上可能出现远端用户音量随机变化的问题。 - 切换前置、后置摄像头后采集画面可能会瞬间旋转。 - 语音路由随机切换,即可能出现插着耳机但是仍然从扬声器出声,或者没有耳机却从听筒出声的情况。 - 连续两次调用 `getUserMedia` 获取相同媒体类型的轨道,第一次获取的媒体轨道会静音或黑屏。 - 使用过其他使用音视频输入设备的 app 后(例如 Siri 或者 Skype 通话),无法采集本地音频或视频。 **影响范围**:HarmonyOS NEXT 5.0 或以上版本的华为浏览器。 **规避方案**:参考以下方案: - 方案一:手动刷新浏览器页面。 - 方案二:调用 `setEnabled` 方法禁用本地音频轨道后再重新启用。 #### 已知限制 [#已知限制] Android iOS HarmonyOS 原因:移动端浏览器及 WKWebView 未实现 `mediaDevices.getDisplayMedia` 接口。 原因:移动端设备在进行美颜算法处理时性能消耗过大。 原因: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](https://developer.apple.com/documentation/avfoundation/avcapturesession/interruptionreason/videodevicenotavailableinbackground?language=objc) 和 [Chromium issue 4294](https://bugs.chromium.org/p/webrtc/issues/detail?id=4294)。 原因:iOS 以及 iOS 上的 WebView 不支持通过设置 `HTMLMediaElement.volume` 属性改变音量。 原因:HarmonyOS 系统问题。 原因:HarmonyOS 系统采集问题。 原因:HarmonyOS 系统问题。 ## 检测浏览器兼容性 [#检测浏览器兼容性] 声网 Web SDK 提供 [`checkSystemRequirements`](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#checksystemrequirements) 方法,用于检测 SDK 是否能在当前浏览器中使用。 ```typescript const result = AgoraRTC.checkSystemRequirements(); // result 为 true 代表支持,false 代表不支持 console.log(result); ``` <_PlatformProcessedMarker close="true" />