Web 常见FAQ

参考文档：官网文档解释

注意
为保证最佳的用户体验，Agora 强烈推荐使用桌面端 Google Chrome 浏览器官方最新版本。

以下场景中请务必将 Web SDK 升级至最新版本：

• iOS 12.1.4 及以上版本上使用 Safari 浏览器。
• macOS 上使用 Safari 12.1 及以上版本。

参考文档：官网文档解释

对于 v3.0.0 及以上版本的 RTC Native SDK，与 Web SDK 的互通是默认打开的，无需设置。

而 v3.0.0 之前的 SDK，通信场景下，Web SDK 和 Native SDK 默认互通，无需额外设置。在直播场景下，移动端/桌面端和 Web 端必须同时手动设置，才能实现互通。

参考文档：官网文档解释

注意：上文仅适用于 Agora Web SDK 3.x 及之前版本。

Agora Web SDK 新增 H5 实时直播组件，支持在移动端网页播放音视频流。该功能可以实现通过在社交 app 内（如微信群、微信公众号、钉钉）分享网页链接，让用户在 app 中打开链接就能直接观看实时视频，降低了分享门槛，方便扩大目标受众范围。

参考文档：官网文档解释

注意：高清视频 HD 和超清视频 HD+ 是由单个用户订阅的所有流的集合分辨率决定的。
集合分辨率为所有被订阅的视频流的分辨率之和，并且会经过分辨率校准将视频流的水平像素及垂直像素个位数归零（做进位处理）。

参考文档：官网文档解释

Cannot read property “appendChild” of null

错误原因

播放指定的 DOM 不存在或者 ID 没有找到。

解决办法

确保在调用 Stream.play 方法时已生成相应的父容器。

Cannot read property ‘stringuid’ of undefined

错误原因

在还未成功加入频道时调用了 Client.publish 方法。

解决办法

检查你的集成逻辑，确保在调用 Client.publish 时已成功加入频道。

Connect choose server timeout

错误原因和解决方法同 Failed to load resource。

DTLS failed

下表列出了常见的错误原因和相应的解决办法。

如果按照以上方法排查后仍然报错，请联系 Agora 技术支持。

Failed to execute ‘addStream’ on ‘RTCPeerConnection’: parameter 1 is not of type ‘MediaStream’

错误原因

在 Stream.init 尚未成功时就调用了 Stream.publish 。

解决办法

在 Stream.init 成功的回调中调用 publish 方法。

Failed to load resource

错误原因

用户本地的 DNS 解析错误。

解决办法

建议用户根据所在区域修改 DNS 服务器的地址后重新加入频道：

• 中国大陆用户将 DNS 服务器设为 114.114.114.114 。
• 中国大陆之外的用户将 DNS 服务器设为 8.8.8.8 。

Failed to set remote answer sdp: Called in wrong state: kStable

错误原因

调用 switchDevice 导致报错。

解决办法

该错误没有任何影响，忽略即可。

Invalid elementID

错误原因

Stream.play 中指定的 HTMLElementID 不合法。

解决办法

确保 HTMLElementID 字符串仅包含 ASCII 字符集中的字母和数字，或 “_”、"-"、"."，且字符串长度大于 0 小于 256 字节。

INVALID_VENDOR_KEY

错误原因

可能的原因有：

• 使用的 App ID 无效。例如 App ID 对应的 Agora 项目处于禁用状态，或者新建的 Agora 项目 App ID 尚未生效。
• 使用的 token 无效。

解决办法

检查 Client.init 中 appId 和 Client.join 中 tokenOrKey 的设置，确保使用有效的 App ID 和 token。

Media access MEDIA_NOT_SUPPORT: video/audio streams not supported yet /enumerateDevices() not supported

错误原因

可能的原因有：

• 使用的浏览器不兼容 Agora Web SDK。
• 没有使用 HTTPS 协议或者 localhost 打开页面。

解决办法

• 使用 Agora Web SDK 支持的浏览器。
• 使用 HTTPS 协议或者 localhost 打开页面。

NO_CANDIDATES_IN_OFFER

错误原因和解决方法同 None Ice Candidate not allowed。

None Ice Candidate not allowed

错误原因

建立 WebRTC 连接时未找到 ICE (Interactive Connectivity Establishment) candidate。

Candidate 是指用于媒体传输的候选地址，包含 IP 地址和端口信息。

解决办法

根据是否开启云代理，建立连接时会使用不同类型的 candidate，因此解决办法也不同。

• 如果你开启了云代理，SDK 会从 TURN Server 获取 relay candidate，所以你需要检查是否已经将 Agora 指定的云代理 IP 地址和端口添加到白名单，并确保客户端可以正常连接到 TURN Server。
• 如果没有开启云代理功能，SDK 会从本地设备获取 host candidate。获取失败通常是由于安全策略设置导致的，你可以进行以下排查。
  • 检查浏览器是否安装了禁用 WebRTC 的插件。
  • 确保本地设备的防火墙设置未禁用 UDP，且已经将指定的域名和端口添加到白名单。

P2P lost

错误原因和解决方法同 DTLS failed。

UID_CONFLICT

错误原因

一个频道中有多个相同的 uid 。

解决办法

确保频道中每个用户的 uid 是唯一的。

Uncaught DOMException: Failed to execute ‘addTransceiver’ on ‘RTCPeerConnection’: This operation is only supported in ‘unified-plan’.

错误原因

在浏览器上开启了模拟移动设备调试。

解决办法

Agora Web SDK 不支持模拟移动设备调试，请勿使用模拟器进行调试。

Uncaught TypeError: Failed to execute ‘createObjectURL’ on ‘URL’: No function was found that matched the signature provided

错误原因

在浏览器上开启了模拟移动设备调试。

解决办法

Agora Web SDK 不支持模拟移动设备调试，请勿使用模拟器进行调试。

User is not in the session

错误原因

该错误表示尚未建立连接，通常是因为调用 API 时序不正确导致的。例如调用了 Client.leave 之后调用 Client.publish 。

解决办法

检查你的 API 调用顺序。

参考文档：官网文档解释

NotAllowedError

用户拒绝了获取音视频设备的请求

OverConstrainedError

指定的要求无法被设备满足，此异常是一个类型为0verconst rainedError的对象，拥有一个constraint属性，这个属性包含了当前无法被满足的constraint对，如果你开启了多个Tab页同时推流，请确定分辨率采集是一致的。

NotFoundError

找不到满足请求参数的媒体类型。

一类已知问题：用户采用第三方的虚拟摄像头软件，会导致 chrome 识别不了这个摄像头，但是 360 浏览器能识别，原因： 该虚拟摄像头软件是 32 位的软件 ，只有 32 位的应用才能使用，所以需要安装 32 位的 chrome 才可以识别。

NotReadableError

尽管用户已经授权使用相应的设备，操作系统上某个硬件、浏览器或者网页层面发生的错误导致设备无法被访问。

一类已知问题：部分 win10 的笔记本需要用 Chrome 兼容 win7 的模式打开才能使用摄像头，不然会报错：could not start video source

AbortError

尽管用户和操作系统都授予了访问设备硬件的权利，并且也没有出现 NotReadableError 这类硬件引起的问题，但仍然有一些其它问题的出现，导致了设备无法被使用。

TypeError

constraints 对象未设置[空]，或者都被设置为 false。

SecurityError

没有使用 HTTPS 或 localhost 协议。

QQ、微信是应用层的直接调用，而 Agora Web SDK 依赖于浏览器开放的 WebRTC 技术，相比 QQ 和微信 中间隔了一层 WebRTC 的封装。可以理解为浏览器自己把音视频采集能力封装一层之后兼容性做的不够好，导致我们上层的应用出现这种情况。
对于这类问题，一般建议按照以下步骤进行排查：
1、检查声音驱动，尝试卸载或者升级；
2、更换录音设备，比如换个耳机；
3、更换通话设备，看下有没有问题。

1、视频黑屏
一般都是设备导致的问题，这个时候可以先用 Agora Video Call app 试试。如果 AVC 也不行的话，转战 WebRTC 原生 demo ，打开之后看看 console 里面有什么报错。
一般错误：

• could not start video source
• navigator.getUserMedia error: {name: “NotReadableError”, …}

建议的解决方案：

• 尝试在设备管理器里面卸载相机或者图像驱动，然后点击操作中的扫描检测硬件改动，会自动重装驱动，之后再检测是否可用。
• 如果还是不行的话，用第三方工具（360驱动大师等）更新相应驱动，重启电脑后再行测试。

2、视频采集帧率低
先使用 Agora Web Demo 或者 WebRTC 原生 demo 测试一下，看下几个主流分辨率配置下，是否都会采集帧率低。有可能是因为某些摄像头本身就存在一些问题，导致不适配某种分辨率。

发送端排查步骤：
建议用户做以下紧急处理：
1、如果持续 10 秒听不到，让用户刷新浏览器页面再看看。不行的话请关闭浏览器再重新打开，进入频道。

2、如果还是不行，请打开这个 demo ，然后看 console 里面是否有报错或者警告信息。音频设备的报错一般都是 could not start the audio source，有这个报错的话说明浏览器通过驱动调查设备的时候出错了，很可能是这个设备有异常或者驱动有问题，这个时候可以直接跳到第三步排查步骤。如果没有这个报错的话，说明浏览器可以调用输入音频设备，但是未知的原因导致拿不到音量数据，这个时候打开 demo ，然后对着听筒说话，instant（瞬间音量）和 slow（持续音量）会有波动（instant 能变化到绿色就表明老师采集没有问题）。
如果用上述 WebRTC 官方 demo 测试音量就有问题，那么问题基本就是浏览器和设备的交互异常，这个时候先参考第三步的方式测试一下，然后跳到第四步。

3、打开 windows 中的声音控制面板，点击声音录制设备，看看用户设备里面有几个输入音频设备并且默认用的是哪一个，建议把麦克风阵列设置为默认设备/默认通信设备（可以的话把其他录制设备都禁用掉），然后刷新页面，重新测试看下是否能恢复采集。
如果还不行的话，根据已有经验，可以检查用户端的声卡驱动：windows 用 chrome60 以上版本的浏览器可能会出现采集没有声音的问题，建议用软件（ 360 驱动大师、驱动精灵等软件）查看本地的声卡驱动是否能够更新、以及声卡驱动发布的时间点，一般声卡驱动都是 2015 年之前或者更老的版本，建议用户自行升级声卡驱动，然后重启电脑之后测试是否采集恢复正常。

4、如果用户调用设备没有问题，但是音量就是很小很小，检测驱动也是最新版本，这个时候可以查看输入音频设备的详细信息，看一下驱动版本更新历史：
1）在某些电脑上，回退驱动版本，设备采集可能可以恢复正常；
2）很大可能用户那边有几个音频输入设备，默认都麦克风阵列不可用，但是其他的比如混音可以用，但是我们要的结果是把麦克风调试成可用的。按照现在的经验来看，设备音频突然出现问题，99.9% 和音频驱动相关，好好琢磨驱动的调整基本都能解决问题。

5、对于经常出现问题的用户，使用前一定一定一定要做好自检，这样才可以保证通话质量。
inputelevel 查看方式：
打开 chrome://webrtc-internals/ 点击相应的连接，点击 Stats graphs for ssrc_*********（随机id）_send (ssrc) (audio) ，里面会显示音频采集发送的所有信息

参考文档：官网文档解释

数据可能需要耗费 0-3 秒时间返回。试下循环调用：

setInterval(() => {
    rtc.client.getTransportStats(stats => {console.log(JSON.stringify(stats))})
}, 1000)

参考文档：官网文档解释

使用Web SDK出现看得到画面但是听不到远端声音以及可能无声又无图的现象需要检查是否由于浏览器的自动播放策略限制导致：音频轨道的自动播放会失败(视频轨道的播放一般不受限制)，如何处理可以应对这种限制。

需要注意如下几点：

• 主流的浏览器Safari、Chrome、firefox对Autoplay的具体策略实现，是不一样的，甚至不同的版本，也会不一样。其中，最严格的是Safari浏览器，需要特殊处理前端集成代码。
• console中如有该报错则需要注意是否自动播放限制导致无声问题： NotAllowedError: The request is not allowed by the user agent or the platform in the current context, possibly because the user denied permission.
• 所谓的用户交互，指的是触摸屏的触摸事件，键盘事件、鼠标事件等，即，需要有最终真实用户的实际交互。
• 不论web sdk 3.x版本还是4.x版本，我们都无法“绕过”浏览器自动播放策略，只能“利用”浏览器自动播放策略。

解决方法：

一般情况下添加如下代码

let isAudioAutoplayFailed = false;
AgoraRTC.onAudioAutoplayFailed = () => {
if (isAudioAutoplayFailed) return;

isAudioAutoplayFailed = true;
const btn = document.createElement(“button”);
btn.innerText = “Click me to resume the audio playback”;
btn.onClick = () => {
isAudioAutoplayFailed = false;
btn.remove();
};
document.body.append(btn);
};

iOS Safari/WebView 的特殊处理

iOS Safari 只允许通过用户交互来 触发 有声媒体的播放，而不是在用户交互后就打开 Autoplay 限制。

如果你的应用需要兼容 iOS Safari/WebView，我们推荐对 iOS Safari/WebView 做特殊处理。

• 为每个远端用户在播放界面上通过图标显示当前用户被静音，引导用户点击。
• 当本地用户点击某个远端用户的音频播放按钮时，在按钮的点击/触摸事件的回调中播放这个用户的音频轨道，同时更改静音图标。

// HTML
<div id="user1-audio">已静音</div>

// JavaScript
document.getElementById("user1-audio").onClick = (e) => {
    if (user1.audioTrack.isPlaying) {
        user1.audioTrack.stop();
        e.target.innerHTML = "已静音";
        return;
    }
    user1.audioTrack.play();
    e.target.innerHTML = "播放中";
}