该部分包含在使用 Agora SDK 过程中可能遇到的故障及解决方法。

音频相关

回声

回声问题通常是由听到回声的用户设备引起的。SDK 支持对多数设备进行回声消除。如果遇到回声问题，可以佩戴耳机进行规避，并确认耳机本身不会引起回声。

步骤 1：自检操作

判断回声是持续性的还是一次性的。后者是由设备性能过度使用引起的，可从声网提供的水晶球服务中进行确认。
请确保各通话方处于互相隔离的物理环境中（非近场测试）。
请检查 SDK 版本，如果低于以下版本，请升级至以下版本再尝试：
- Android/iOS: v1.6.0 或更高版本
- Windows/macOS: v1.7.0 或更高版本
确认音频是否使用了自采集模式。自采集本身不会引起回声，但在传输给 SDK 的过程中，可能会因为数据不完整而产生回声。该模式 SDK 不支持回声消除。
Windows 平台上，检查在麦克风属性里是否已勾选监听麦克风选项，如有，取消该勾选。
iOS 平台上，检查是否设置了 Mixable option，并且有其他音频类应用也在使用 Mic，这种情况可能会导致回声。
Android 平台上检查是否使用了 setAudioProfile 的 GameStreaming 场景，该模式下回声消除默认关闭。
请佩戴耳机。
- 1 对 1 通话：如果您听到回声，请让对方佩戴耳机进行通话。
- 多人通话：可以请用户轮流静音，找出回声源。引起回声的用户请佩戴耳机，或在无需发言时，请将自己设为静音状态。

步骤 2：联系技术支持

如果问题仍然存在，请联系技术支持，并提供以下信息，方便快速定位问题：

image.png1120×455 21.3 KB

噪声

噪声的问题一般是外部环境或者录放音设备导致的，SDK 本身一般是不会主动产生噪声。

步骤 1：自检操作

完成以下的自检操作，确认噪声是否已消除：

确认是否为近场测试：通信两端的手机在同一房间内，且处于公放状态，连环增益大于 1 时会产生近场啸叫。
确认音频是否使用了自采集模式。自采集本身不会引起噪声，但在传输给 SDK 的过程中，可能会因为数据不完整而产生噪声。该模式 SDK 不支持噪声消除。
通话时一方环境是否太过嘈杂（麦克风对着电脑风扇，宿舍很吵，窗外很吵等）。
确认录音设备是否正常工作（外置声卡、耳机、麦克风接触不良会造成电流声）。
耳机 Mic 晃动或和衣服摩擦也会产生杂音。

步骤 2：联系技术支持

如果问题仍旧存在，请联系技术支持，并提供以下信息，方便快速定位问题：

image.png1114×454 21.6 KB

音量问题

步骤 1：自检操作

请检查接收方的系统音量是否已调大。
请检查该问题是否由您的设备引起的，例如，更换耳机或者其他播放设备，或在您的 PC 店或移动端，测试其他同类 VoIP 引用是否也存在声音小的问题。
请确认在通话过程中是否使用了第三方的音频应用，因而改变了音频系统底层的设置或者路由，请开发者自行检查代码逻辑。
调用以下 API 获取音量信息，调节音量大小： enableAudioVolumeIndication ， adjustRecordingSignalVolume ， adjustPlaybackSignalVolume ，和 adjustAudioMixingVolume 。详见各平台的 API 参考说明文档。
在 onAudioRouteChanged 回调里检查语音路由到听筒还是外放(扬声器)。如果是听筒，请调用 API setDefaultRouteToSpeakerphone 将语音路由修改至从外放出声。

步骤 2：联系技术支持

如果问题仍然存在，请联系技术支持，并提供以下信息，方便快速定位问题:

用户所在的频道名称；
哪些用户反映音量过小，请提供他们的 UID；
用户发现音量过小的时间段。

直播模式下上麦或下麦时音量为什么变化？这个可以避免吗？

为了保证不同模式下更好的音质体验，默认情况下上下麦 SDK 会调整底层音频的设置。简单来说，非连麦模式下会使用媒体音量控制，连麦模式下会使用通话音量控制，两者有独立的音量控制机制。

如果想要避免音量变化，可通过 AudioProfile 中 Scenario 的设置来指定通话音量或者媒体音量，Android 平台建议使用 CHATROOM_ENTERTAINMENT，iOS 平台建议使用 GAME_STREAMING 模式。

听不到声音

用户在通话过程无法听到对方的声音，或者其他人听不到该用户的声音，或者双方都听不到声音。

步骤 1：自检操作

完成以下的自检操作，确认问题是否已解决：

请确保双方均开通了音频设备的使用权限。
请确保双方已成功加入频道，是否收到 onJoinChannelSuccess 回调事件。
请检查是否误操作将自己或对方设为了静音状态。
请检查是否调用了SDK相关接口主动静音： adjustRecordingSignalVolume 或 adjustPlaybackSignalVolume 。
请检查录音设备是否能录音成功。您可以调用API方法 startEchoTest 进行测试。
请确认耳机是否正常工作。
请调用 setEnableSpeakphone 进行设置，在外放模式下，插入耳机是没有声音的。
如果确认已将语音路由到耳机，请检查耳机是否正常工作。
请在 Agora 官网下载在视频通话的示例代码，检测您的设备是否正常。
Windows 平台上，如果用户通过外放或耳机听不到声音，可采取下列措施进行排查：
a. 右键点击 扬声器 ，选择声音。

b. 在播放页签下，确认图中绿色部分是否随着播放的音量大小发生变化。不然，说明播放设备无法正常工作。

如果绿色部分随着播放的音量大小而变化，确认使用其他程序能否听到声音。如果能听见声音，说明是你的 App 存在问题。如果无论使用哪个程序，绿色部分均不出现，尝试插拔耳机，更换播放设备，或静音再重启播放设备。
c. 如果上述所有方法均不见效，采取下列措施检查录音设备是否正常工作：
点开录制页签，确认图中高亮的绿色是否会随着讲话声音发生变化。如有多台设备，请选择一台合适的设备进行测试。

步骤 2：联系技术支持

如果问题仍然存在，请联系技术支持，并提供以下信息：

用户无法听到声音的频道号
该频道内哪些用户无法听到声音，请提供他们的 UID
用户无法听到声音的时间段

卡顿

卡顿的问题可能涉及到网络，设备，物理环境等原因。比较常见的是客户端的网络较差导致。

步骤 1：自检操作

检查网络状况是否良好。可以换到 4G 或更稳定的 WiFi 环境下再尝试。

也可通过声网提供的水晶球服务，确认用户的网络、设备 CPU 使用是否正常。

步骤 2：联系技术支持

如果问题仍旧存在，请联系技术支持，并提供以下信息，方便快速定位问题：

image.png1114×403 16.4 KB

步骤 3：水晶球监控通话质量
你可以使用 Agora Dashboard 的水晶球功能对通话质量进行跟踪和反馈，详见水晶球教程。

iOS 蓝牙耳机相关问题

iOS 会自动为系统电话和 VoIP 通话选择音频路由。即使用户连接了蓝牙设备已经连接，也不一定使用蓝牙接听电话。

系统电话（包括 CallKit）

系统来电时：

如果用户是在 iPhone 设备上按了接听键，来电默认走 iPhone 听筒；
如果用户是在蓝牙设备上按了接听键，来电默认走蓝牙。

系统的默认行为可以设置，在 iPhone 的 设置 > 通用 > 辅助功能 > 音频通话方式 ，上述行为是默认的自动。如果设为蓝牙耳机，则来电的时候即使在手机接听，也默认走蓝牙耳机。

在系统电话过程中，用户可以通过通话界面的外放按钮自行切换蓝牙、听筒或外放。

VoIP 通话

在发起 VoIP 通话的时候，系统会自动选择音频路由为：当前蓝牙设备连接后的最后一次系统电话或 VoIP 通话所使用的音频路由。如果蓝牙设备连接后没有过系统通话则使用蓝牙。

在 VoIP 通话过程中，用户可以通过系统控制中心（从屏幕下方上滑）自主切换音频路由。程序则可以通过 setPreferredInput 接口切换路由。

其他设定

用户指定或者程序指定了蓝牙设备为输入或输出时，系统会自动把输出或输入也切到蓝牙。不支持输入输出在两个不同设备上。

无线蓝牙音箱的录音功能只有系统电话级的才可以使用，如：系统电话、FaceTime、或 CallKit。

常见问题

Q：我正用蓝牙耳机在 VoIP App 中进行通话，这时候接听了一个系统电话，再回 App VoIP 就变成听筒了？
A：如果你点手机上的接听按钮，系统电话和 VoIP 的默认路由就变成了 iPhone 听筒。如果你点蓝牙耳机上的接听按钮，再切回 App 就能保持使用蓝牙耳机进行通话。

Q：iPhone 连着蓝牙耳机，但是在 VoIP 中加入频道就自动变成听筒或外放？
A：这是由于当前系统电话和 VoIP 的默认路由不是蓝牙耳机。进行 VoIP 通话前，在系统控制中心（从屏幕下方上滑）中手动切到蓝牙设备，下次再加入频道就默认使用蓝牙了。

Q：为什么音乐播放可以自动切回蓝牙？
A：音乐播放不是 VoIP 通话，没有这个行为。

Q：为什么连着蓝牙音箱，进入通话是听筒或外放？
A：除非使用 CallKit 框架，不然一个 App 的通话是无法由无线蓝牙音箱录音的，也就导致了无法使用无线蓝牙音箱播放。直播的观众模式，因为不需要录音，所以可以使用无线蓝牙音箱播放。

视频相关

卡顿

视频卡顿问题一般由网络、设备性能等原因造成，请按以下步骤进行排查：

判断是持续性的还是一次性的卡顿。后者是由网络和设备的随机性导致，属于正常现象；
检查网络状态，判断连接是否正常，是否能够上网；
如果网络连接正常但依然卡顿，请尝试 4G 连接或其他 WiFi 信号，找到网络状态良好的条件下情况如何；
如果网络良好且条件允许，请尝试更换设备；
如果有视频前处理，例如美颜等，请先关闭前处理，确保卡顿不是由于前处理导致的。

如果上述措施没有解决问题，请收集下面信息并联系技术支持：

卡顿用户的 UID，如果是直播场景，需要提供这个卡顿是来自于主播还是连麦嘉宾；
卡顿的具体时间段；
如果频道中有语音，检查语音是否流畅、清晰；
卡顿用户的 SDK 日志及录屏文件。

你可以使用 Agora Dashboard 的水晶球功能对通话质量进行跟踪和反馈，详见水晶球教程。

模糊

视频模糊一般是由视频码率或分辨率过低导致，请按以下步骤进行排查：

确认 videoProfile 设置，如果可以的话，尝试更高的 profile 看是否可以解决问题；
看看接收端接受的是大流还是小流，是小流的话可以调用接口申请大流关闭小流；
尝试 4G 连接，或者其他 WiFi 信号排除网络问题；
如果有视频前处理，请先关闭前处理；

如果上述措施没有解决问题，请联系技术支持并提供下列信息：

出现模糊画面的用户的 UID；
模糊的具体时间端；
出现问题的用户的 SDK 日志及录屏文件。

你可以使用 Agora Dashboard 的水晶球功能对通话质量进行跟踪和反馈，详见水晶球教程。

黑屏

可能出现黑屏的原因有很多，其中两个最重要的原因是：

网络问题：如果本地网络连接很差或者中断，就会看不到其他用户的视频。如果通话中有一方的网络出现问题，其他人也看不到这个用户的视频。
用户主动关闭了视频，也会出现黑屏。

黑屏主要有以下三种情况：

本地视频黑屏远端视频正常

这种情况一般是摄像头故障或者被占用等原因导致本地视频采集出现问题，请按以下步骤排查：

摄像头硬件问题。打开系统自带的拍摄视频程序看是否可以录像，如果不行，需要换摄像头；
如果摄像头没有问题，看下摄像头权限有没有打开。Android 和 iOS 系统都有权限管理，请在系统设置中检查，同时 Android 上有些安全软件也管理权限；
是否有其他应用占据了摄像头。关闭其他应用然后打开我们的应用测试；重启手机再测试；
检查是否是用户禁用了本地视频；
如果是自采集，需要确认外部采集数据是否有问题。

本地视频正常远端视频黑屏

这种情况可能是远端采集问题或者本地下行网络原因导致，请按以下步骤排查：

检查用户是否禁用了远端视频；
如果没有禁用远端视频，建议换4G网络看下是否还存在问题来排除网络原因。

本地远端视频都黑屏

这种情况可能是渲染出现问题或者没有启用视频，请按以下步骤排查：

检查是否有调用 enableVideo 方法启用视频；
检查是否有禁用本地及远端视频；
如果上述都没有问题，可能是渲染问题，Windows 端检查 SDK 日志，看渲染方式（render type）是什么。如果是 D2D 渲染，很可能是显卡驱动不是最新，建议去显卡官网更新显卡至最新版。如果更新完官方驱动还是不行，建议走设置 GDI 渲染方式，即加入频道前调用下面的方法：
- AParameter apm(*pRTCEngine);
- nRet = apm->setInt("che.video.renderer.type", 9);
如果是自渲染，需要确认渲染方式是否有问题。

如果按照上述步骤没有解决问题，请收集下面的信息并联系技术支持：

已经做过的排查步骤及结果；
黑屏用户的 UID；
黑屏的具体时间段；
出现问题端用户的 SDK 日志。

镜像

如果远端看到镜像的视频：检查 App 是否调用了 setParameters (audioEngine.remoteVideoMirroring)。
如果是本地预览发生镜像：

手机的前置摄像头就是镜像的，属于正常现象；
其他情况发生镜像，检查 App 是否调用了 setParameters (che.video.localViewMirrorSetting)。

如果镜像问题不属于上述情况，请联系技术支持并提供下列信息：

使用了哪个摄像头，是本地预览镜像了还是远端镜像了；
希望是镜像效果还是非镜像效果。

无法打开摄像头

摄像头打开失败有多种原因，请按以下步骤检查：

确认摄像头权限有没有打开。Android 和 iOS 系统都有权限管理，请在系统设置中检查。同时 Android 上有些安全软件也管理权限。
检查是否有其他应用占据了摄像头。关闭其他应用，重启手机再试。
摄像头硬件问题。打开系统自带的拍摄视频程序看是否可以录像。

显示大头/黑边

这种情况一般是由于视频尺寸与显示视窗尺寸不一致，有下面几种情况：

如果是视频宽高和摄像头输出不一致，会在编码前发生裁剪导致视频放大；
如果接收端渲染使用的是 hidden 模式，并且视频尺寸与显示视窗尺寸不一致时，会发生裁剪导致视频放大；
如果接收端渲染使用的是 fit 模式，并且视频尺寸与显示视窗尺寸不一致时，会发生缩放导致黑边。

如果排除上述几种情况后问题仍存在，请联系技术支持并提供下列信息：

发送方的 SDK 日志；
发送方如果是手机，检查发送方是横屏还是竖屏；
接收方的窗口长宽比。

直播相关

为什么旁路直播和旁路直播的录制内容里只听得到声音，却看不到视频?

检查一下 API setLiveTranscoding 是否已正确调用。

为什么两个主播进入同一个频道却看不见对方？

请完成以下的自检操作，确认是否能够解决问题：

确认两个主播是否使用相同的 App ID。如果同一个客户注册多个 App ID，请不要混淆；
确认两个主播是否进入相同的频道（频道名相同）。
确认两个主播的网络是否连接正常。

为什么设置分辨率为 640 360，实际却为 640 352？

由于 Android 的部分机型受编码器限制，只支持视频宽度是 16 的倍数，所以我们将分辨率统一设为 16 的倍数。例如宽度为 360 时，实际上宽度为 352。

SEI 帧相关问题

声网 SEI 规范

在默认情况下，声网进行服务端转码推流时，会在转码后的 H264/H265 的 SEI 帧中，增加当前视频的编码信息。该信息为 Json 格式的字符串，具体示例如下：

{
    "canvas": {
        "w": 640,
        "h": 360,
        "bgnd": "#000000"
    },
    "regions": [{
        "uid": 1,
        "alpha": 255,
        "zorder": 1,
        "volume": 50,
        "x": 0,
        "y": 0,
        "w": 320,
        "h": 360
    }, {
        "uid": 2,
        "alpha": 1.0,
        "zorder": 1,
        "volume": 89,
        "x": 320,
        "y": 0,
        "w": 320,
        "h": 360
    }],
    "ver": "20180828",
    "ts": 1535385600000,
    "app_data": ""
}

各项参数定义如下：

canvas：画布信息，画布的参数信息如下；
- w：画布的宽度，单位为像素。主播在 APP 设置的 LiveTranscoding 中的 width 信息；
- h：画布的高度，单位为像素。主播在 APP 设置的 LiveTranscoding 中的 height 信息；
- bgnd：画布的背景颜色，RGB 格式，为 16 进制代码表示的字符串。主播在 APP 设置的 LiveTranscoding 中的 backgroundColor 信息；
regions：主播信息及主播布局信息，为 region 的列表。主播在 APP 设置的 LiveTranscoding 中的 transcodingUsers 信息。region 的参数信息如下；
- uid：该区域对应主播的 ID。主播在 APP 设置的 TranscodingUser 中的 uid 信息；
- alpha：该区域的透明度，取值范围 [0, 255]。主播在 APP 设置的 TranscodingUser 中的 alpha 信息；
- zorder：该区域的层级，取值范围 [1, 100]。主播在 APP 设置的 TranscodingUser 中的 zOrder 信息；
- volume：该区域对应主播的音量大小，取值范围 [0, 255]；
- x：该区域在画布中对应的 x 坐标。主播在 APP 设置的 TranscodingUser 中的 x 信息；
- y：该区域在画布中对应的 y 坐标。主播在 APP 设置的 TranscodingUser 中的 y 信息；
- w：该区域的宽度。主播在 APP 设置的 TranscodingUser 中的 width 信息；
- h：该区域的高度。主播在 APP 设置的 TranscodingUser 中的 height 信息；
ver：版本信息，当前版本为 20180828；
ts：生成该信息时的时间戳，单位 ms；
app_data：自定义信息。主播在 APP 设置的 LiveTranscoding 中的 transcodingExtraInfo 信息；

SEI 构成

下面是一段 SEI 帧的内容：

0000 0664bd7b 22617070 5f646174 61223a22 .d.{“app_data”:"

0010 222c2263 616e7661 73223a7b 2262676e ",“canvas”:{"bgn

0020 64223a22 23666666 66666622 2c226822 d":"#ffffff",“h”

0030 3a363430 2c227722 3a333630 7d2c2272 :640,“w”:360},"r

0040 6567696f 6e73223a 5b7b2261 6c706861 egions": [{"alpha

0050 223a3235 352c2268 223a3634 302c2275 ":255,“h”:640,"u

0060 6964223a 33313031 32373137 39312c22 id":3101271791,"

0070 766f6c75 6d65223a 32382c22 77223a33 volume":28,“w”:3

0080 36302c22 78223a30 2c227922 3a302c22 60,“x”:0,“y”:0,"

0090 7a6f7264 6572223a 317d5d2c 22747322 zorder":1}],“ts”

00a0 3a313533 37393630 32333537 38332c22 :1537960235783,"

00b0 76657222 3a223230 31383038 3238227d ver":“20180828”}

字段说明：

06：SEI 帧；
64：用户定义的帧类型，这里声网定义 SEI 类型为 100；
bd：帧长度。如果帧长度超过 255，例如 922，则表示为 ffffff9d;
其余部分：帧内容；

Q&A

Q：是不是只要在这儿用了SEI，就不能用信令传布局了？SDK传的是同一个字段，传递方式（信令或SEI）只能二选一？

A：这个是服务端推流时，在 H264/H265 的 SEI 帧中添加的信息，跟 APP 上行发送的数据不是一个概念。与 APP 上行发送的数据唯一相关的是 app_data 字段。

在新直播系统中，有效的方式仅有 LiveTranscoding 这个配置信息，旧直播系统的相关接口不再生效。

Q：布局信息不是通过信令传的嘛？这边为啥也要写上布局信息？不只是音量信息？

A：声网一直以来都会在合图推流中，发送 SEI 相关信息，但是一直没有进行规范化。此次修改规范化了 SEI 格式，并增加了音量信息，向前兼容。

加入布局信息的原因是，观众端有可能需要当前的布局信息，进行窗口边框的描绘。

游戏相关

游戏音效问题

进入指挥模式语音频道之前，通过系统的静音键将游戏的音效静音了，但是进入频道之后，为什么游戏的音效就被自动打开了？

通话过程中，通话音量都无法降为 0。所有类似软件都有相同的现象，包括微信等等。进入通话后，音效播放的也是从通话音量出来的。

打开游戏音效，设置一定的系统音量不改变，进入频道后听到的游戏音效的音量，明显比进入频道之前听到的游戏音效的音量高。

媒体音量 + 通话音量分别属于 2 个不同的、独立的系统，一个设置不会影响到另外一个。进入通话后，音效播放的也是从通话音量出来的。退出通话后，走的媒体音量。例如，王者荣耀的连麦、断麦也是这样。

iOS 上开了游戏、游戏语音后，启动语音并立马退出语音房间，然后游戏背景音就变小了。 Android上是 OK 的。

退出语音房间时，把 AudioSession Category 和 Mode 设置回进房间之前的设置。

在 join 之前，使用 unity 播放游戏背景音乐，对应的 audio session category 为 AVAudioSessionCategoryAmbient ，mode 为 AVAudioSessionModeDefault ，对应一套 volume（媒体音量）。

在 join之后，agora sdk 将 audio session 的 category 更改为 AVAudioSessionCategoryPlayAndRecord ，mode 为 AVAudioSessionModeVoiceChat ，对应另一套 volume（通话音量）。

接入 SDK 后游戏音乐音效与语音相互冲突。

必然有的问题。加频道的一个过程，会断一下。可以设置为只走媒体音量，但是有回声等问题。

麻将棋牌游戏中，4 个人的背景音乐会被相互串到通话里面？

如果是客户自己播放的音频，不是经过声网的 API 播放的背景音乐，是会存在这个问题的。开通话的时候，直接关掉音乐和音效,就没有了。

在 app 里播放背景音乐，然后开加入频道，这个时候背景音乐音量变化，当调用了 leaveChannel 之后背景音乐也没有了。

在 joinChannel 之前，加入： setParameters("{\"che.audio.keep.audiosession\":true}") ;

在播放背景音乐的情况下，join channel 后，听到的背景音乐声音会变小。

在 join channel 之后背景游戏音乐播放仍留在 earpiece 没有切到正确设备（扬声器），造成声音听起来较小。app 调用 setEnablespeaker 确保背景音乐和通话音的 output route 一致。

onAudioVolumeIndication 获得的音量是 0~255, 有没有什么合适的经验阈值界定说话和没说话?

40～50。客户在此基础上调整一下，不同的人对说话、没说话的定义不一样。

AMG SDK中媒体音量系统，在连麦后进入通话音量系统时，原来媒体音量系统播放的背景音效不能调节？

在 joinChannel 前设置一下接口。

iOS 平台

mRtcEngine.setParameters("{"che.audio.use.remoteio":true}");

Android 平台

mRtcEngine.setParameters("{"che.audio.stream_type":3}");
mRtcEngine.setParameters("{"che.audio.audioMode":0}");

Android 和 iOS 通用的设置

mRtcEngine.setParameters("{"che.audio.enable.aec":true}");
mRtcEngine.setParameters("{"che.audio.enable.agc":true}");
mRtcEngine.setParameters("{"che.audio.enable.ns":true}");

蓝牙耳机为什么没有立体声？

因为蓝牙要开通话模式，即 SCO，才能实现双向（播放、录音）。蓝牙在 SCO 模式下只能单声道播放。蓝牙在 A2DP 模式下可能是双声道的。如果蓝牙音箱只支持 A2DP 不支持 SCO 的话，是无法用来进行语音通话的。

A2DP：是一种单向的高品质音频数据传输链路，通常用于播放立体声音乐。
SCO：则是一种双向的音频数据的传输链路，该链路只支持 8K 及 16K 单声道的音频数据，只能用于普通语音的传输。

设备兼容性问题

Android 与 iPhone 耳机可以兼容吗？

不能。iPhone 耳机接口的左右声道、mic 的排列跟 Android 手机是不一样的。

录制相关

录制SDK

开始录制后，为什么没有录制文件？

请检查 appId 设置的是否与客户端使用 Agora Native SDK 时设置的一样。
请检查 channelProfile 的模式是否与客户端使用 Agora Native SDK 设置的一样。例如，录制的设为直播模式，Agora Native SDK 设置通信模式，直播和通信模式的视频无法互通，因此不会有录制文件。

录制结束后，为什么检查录制的视频没有声音？

录制的音视频文件为独立的，视频为 mp4 格式文件，语音为 aac 格式文件。视频文件本身不含语音，你需要手动转码将多个音视频文件合并成一个文件。若检查发现已是转码合成后的最终视频文件，联系技术支持。

录制结束后，为什么无法播放录制的 MP4 文件？

请参考播放器列表，查看是否使用了不支持的播放器。

启用加密模式后，为什么无法播放录制的视频文件，声音也不正常？

启用加密模式后，如果密码输入不正确或者没有输入密码，录制的文件无法播放。

由于语音被加密了，导致声音不正常。

当我将加密密码设置为跟客户端一样时，为什么录制仍然不成功？

请确保加密模式与客户端设置的一样，小写的 aes-128-xts 或 aes-256-xts 。

如何使用 Channel Key?

详见Channel Key 密钥说明。

当启用合流模式之后，为什么只有一个 uid 为 0 的录制文件？

这是默认的设计，当启用合流模式后，多个用户加入频道，所有人的语音会被录制在同一个文件里，uid 为 0。

如何对录制文件进行转码?

关于如何手动对录制文件进行转码，详见录制音视频。

如果出现问题，请联系客户支持分析和定位问题。

我可以自己设置录制文件的路径和文件名？

你可以自己设置录制文件的根目录，但是自己无法命名。详见录制音视频。

如何保证同时录制的频道数没有超过服务器容量(CPU/内存)?

请参考文档设置开发环境。

为什么客户端可以加入频道，而录制端无法加入频道（录制端可以发包，但是却收不到来自 Agora 服务器的包）？

请检查防火墙配置，详见设置开发环境。

可以指定只录某个用户的音视频么?

暂时不支持。

如何知道程序是正常退出频道，还是异常退出频道?

如果是正常退出频道，首先 SDK 会触发 onLeaveChanne ，并会返回错误码 ERR_INTERNAL_FAILED = 3。
如果是异常退出频道，SDK 不会触发 onLeaveChannel ，而是触发 onError 并返回错误码 ERR_INTERNAL_FAILED = 3 。

录制文件转码后的格式是什么?

详见录制音视频。

使用命令行时，只输入默认的 must 参数，为何启动不了录制程序？

请检查参数配置，例如在输入 --appliteDir 参数时，只需指到 video_recorder 文件夹，不要指到 video_recorder 这个文件。

为什么录制并转码完成后的视频，在播放的时候，视频前面会黑一小段？

可能的原因如下：

网络不好；
视频包 I 帧收到之后，才会创建视频录制，在此之前收到其他 B,P 帧会丢掉；
视频包的每一帧都比音频的大，所以音频包通常都会比视频包先收到并开启录制。

能录制旋转的视频吗？

录制 SDK 仅保存从 Client 端传来的视频。在生成 mp4 文件时，SDK 会根据 uid_xxx.txt 文件中的信息对视频旋转一次。因此无论视频在录制过程中旋转几次，录制 SDK 只会按 uid_xxx.txt 文件中的第一个旋转信息进行旋转。你可以根据 uid_xxx.txt 文件的旋转信息自己修改转码脚本，然后得到旋转后的视频。目前计划在 2.3 版本中加入使用转码脚本进行视频旋转的功能。

录制文件异常

录制文件夹下没有生成录制文件

确认录制进程是否成功加入到频道。检查录制的 appid 、频道号是否有效，如果开启了 app certificate，是否携带了 channelKey 或 Token，以及 channelKey 或 Token 是否有效。你可以通过通过检查录制日志 recording_sys.log 里的 -appID ， –channel ， –channelKey 参数进行判断。
确认频道内至少有一个 Native/Web 用户。频道内需要至少有一个 Native/Web 用户才能进行录制。如果只有录制客户端，则无法录到文件。如果频道内确认有用户，则还需要确认用户是否有发流，如果没有发流录制也是不会生成文件的。

录制出来的文件时长小于通话时长

通过水晶球检查客户端和录制端在频道内的时间段是否一致。如果一致，联系技术支持。

录制结束之后只有音频文件，没有视频文件。

检查客户端和录制端的频道模式是否一致。
如果频道模式一致，检查录制的参数 isAudioOnly 是否设置为 true，设置为 true 只录制音频，不录制视频。

录制出来的视频，打开播放黑屏，但是声音正常

可能是由于使用了不支持的播放器，请参考播放器列表。

录制出来的视频倒置

请升级至官网最新版本，如还有问题，联系技术支持。

录制文件出现切片

检查 Native/Web 和录制的频道模式是否一致。
频道内同时有 Native/Web 端时，确保 Native 端开启互通 enableWebSdkInteroperability 。

录制出来的文件，音画不同步怎么办

请升级至官网最新版本，如还有问题，联系技术支持。

录制状态异常

录制退出报错

如出现 Error: 3, with stat_code:16 报错时，录制属于正常退出。通过 leave_path code 判断录制退出的原因。

15404521508711458×870

LEAVE_CODE_INIT(0)：初始化失败
LEAVE_CODE_SIG(1<<1)：由信号触发的退出
LEAVE_CODE_NO_USERS(1<<2)：频道内除录制外，没有其他用户
LEAVE_CODE_TIMER_CATCH(1<<3)：捕获到信号错误
LEAVE_CODE_CLIENT_LEAVE(1<<4)：wrapper 层主动退出

日志里的 code 为上面括号内 2 进制移位后的 10 进制数。比如，(1<<1)=2; (1<<2)=4。所以上面的 leave channel with code:12是由 (1<<2)=4 + (1<<3) =8 得来的。

一般都是频道内没有用户，录制正常退出了。检查 recording_sys.log ，是否有 “No users in channel” 的关键字即可确认。

如何判断录制是否崩溃

录制崩溃可能导致以下情况：

视频文件无法播放。
uid_xxx.txt 文件最后没有 mp4 文件的 close 信息。

录制崩溃之后怎么办

请升级至官网最新版本，如果无法解决：

2.2.3 及之后的版本请检查在 AgoraCoreService 同一目录下有没有生成 crash.log 。

2.2.3 之前的版本请检查在 AgoraCoreService 同一目录下有没有生成 core 文件。

如果有生成 core 文件，那么按照下面流程：
a. 把 bin/AgoraCoreService 放在和 core 文件一起，然后命令行执行 gdb -c core_xxxx AgoraCoreService。
b. 将 core 文件、a 中的结果、 recording_sys.log 提供给技术支持。
如果没有找到 core 文件：
a. 如果没有专门设置 core 文件的目录，那么 core 文件一般是在录制的 AgoraCoreService 文件所在的目录。
b. 如果还是没有找到，Linux 上执行 ulimit -c，输出如果为0，则说明 coredump 没有打开，需要通过执行 ulimit -c unlimited 打开。
c. 打开后，之后再出现 crash 就可以生成 core 文件了。
d. 针对这次没有 core 文件生成的场景，提供 recording_sys.log 给技术支持。

Native SDK 与 Web SDK 互通时，在 Native 端录制视频生成的文件是 webm 格式，如何解决？

Native SDK 与 Web SDK 互通时，在 Web 端调用 createClient 方法需要将 codec 属性设置为 h264，如果设为 vp8 则会导致 Native 端的视频录制文件为 webm 格式。

Web SDK相关

用户在安卓设备上使用 Chrome 浏览器发起通话，无法与使用 Native 及 Safari 浏览器的用户互通?

由于 Safari 浏览器通过使用 H.264 视频编码来运行，因此所有 Safari 浏览器上的通话都需要支持该编码。然而当前安卓设备上的 Chrome 浏览器 61 之后的版本有个 bug ，会阻止设备给其他通话方发送 H.264 编码，因此远端的通话方在屏幕上看不到直播的视频，而只能看到一个黑色窗口。安卓设备上的 Chrome 浏览器可以解码来自其他通话方发来的 H.264 编码。

该问题会在 Chrome 浏览器后续版本中解决，我们会持续关注该问题的进展。详见：https://bugs.chromium.org/p/chromium/issues/detail?id=761336

另外，安卓设备的 Chrome 浏览器上也可能会出现通话者只听到声音，但看不到图像的情况。安卓 Chrome 浏览器会在 57 版本中支持解码 H.264。目前安卓手机中只有高通（Kitkat 及以后版本）和三星猎户座（Lollipop 及以后版本）的芯片支持解码 H.264。详见：https://groups.google.com/forum/#!msg/discuss-webrtc/xXjeKbW_JYI/LIXzVrKWCwAJ

H.264 模式下，用户在 macOS 上用 Firefox 浏览器加入通话，打开小流时，获取的分辨率与大流一致？

H.264模式下，在 macOS 设备上使用 Firefox 打开小流时，获取的分辨率与大流相同；如果是 VP8 模式，则没有此问题。Agora 会持续关注并更新在该问题上的进展。

用户在 macOS 上用 Firefox 浏览器 v59.01 版本加入通话，只能看到本地视频，看不到对方视频？

这个问题目前在 Web SDK 2.1 Hotfix 版本上已解决。

两台电脑和一台手机互通时，手机出现屏幕卡住的情况，按 home 键也无法退出?

当 Safari 浏览器、 Chrome 浏览器和移动端加入通话时，有可能会在移动端出现页面冻结或卡住的情况。这是由 Chrome 浏览器发出的 H.264 视频编码导致的。这个问题在使用 Safari 台式电脑与 Safari iOS 互通时不会出现。

详见：
http://bugs.webkit.org/show_bug.cgi?id=176439
http://bugs.webkit.org/show_bug.cgi?id=178357

用户在网页端视频过程中，接了个 QQ 电话，再继续网页视频时，就发送不出音频?

在 Web 端使用浏览器通话过程中，如果有第三方 App 占用音频设备（如系统接听 QQ 电话等），再切换回 Web 端通话时，将无法发送音频信号。建议您退出后重新连接。

Mac 和 Windows 上均使用 Chrome 浏览器通话，如果 Windows 端切换 Wi-Fi，Mac 端画面卡住？

Mac 端需刷新界面后才能恢复画面。Agora 会持续关注并更新在该问题上的进展。

无法加入 channel，报 websocket error，同时会产生类似 ddos 的攻击，短时间巨量的 ws 的连接？

Web SDK join channel 参数数据类型因版本变化有差异。

Web SDK 1.12 及之后的版本中，Join() 增加了Channelkey的属性，详见：https://docs.agora.io/cn/Video/API%20Reference/web/index.html。
Web SDK 1.12 之前的版本中 Join() 中无此属性，详见：https://docs.agora.io/cn/1.8/user_guide/API/webrtc_api.html。

h264_interop 模式下，Firefox 浏览器作为发送端时，接收端切换小流失败？

小流切换与浏览器类型、分辨率、编解码类型相关。各浏览器会根据自己浏览器的内部算法进行调整，因此在进行小流切换时，某些分辨率下会出现小流切换与预计不一致的现象。

直播场景中，在 AgoraRTC.createClient({mode: ‘interop’}) 模式下，Web 单主播如果不设置转码推流，就没有视频？

在 AgoraRTC.createClient({mode: ‘interop’}) 模式下，如果使用单 Web 主播进行推流，需要将 Web 单主播的码流进行转码后再进行推流，否则会出现没有视频的现象。

若要对 Web 单主播直接进行推流，请使用 AgoraRTC.createClient({mode: ‘h264_interop’}) 模式。

请注意，Agora 转码需要收取转码费用。

直播过程中，Safari 浏览器播放第三方音乐后直播音频异常？

经测试分析，使用第三方应用播放音频之后，再切回音视频通话，Safari 的音视频通话会受影响。我们会持续关注该问题，详见：https://bugs.webkit.org/show_bug.cgi?id=179964。

在 Web 端使用 Firefox 浏览器设置视频编码属性进入频道不生效？

在 Web 端使用 Firefox 浏览器时，我们发现部分机器设置的视频编码属性会不生效。这可能是由电脑和浏览器的兼容问题导致的。

目前统计的出现此问题的设备包括：

Macbook Pro(13-inch, 2016, Two Thunderbolt 3 ports)
Windows 10 (MI)

我们会持续关注此问题的最新进展并更新异常设备列表。如果您在使用中遇到此类问题，请将问题反馈给 Agora 技术支持。

iOS 端无法使用 getAudioLevel 方法获取音量？

经测试分析，iOS Safari 端无法使用 getAudioLevel 方法来获取音量，这是由浏览器本身的限制所造成的，我们会持续关注此问题的最新进展。

当 Agora Native SDK 和 Web 用户加入同一直播频道时，PC 或移动端用户可以看见本地和远端视频，但网页端用户看到的远端视频为黑屏，为什么？

PC 或移动端用户（使用 Agora Native SDK 的用户）在直播场景下必须调用 enableWebSdkInteroperability 打开互通功能。

设置视频分辨率为小流模式，但费用却没有按照小流模式计算？

由于设备和浏览器的限制，你设置的分辨率可能不会生效。在这种情况下，Agora 将根据实际分辨率计算费用。

使用 Firefox 浏览器和 Native SDK 互通时，通信模式下，Firefox 浏览器看到的视频方向会旋转，如何解决？

由于浏览器自身的限制，通信模式下建议使用 Chrome 浏览器与 Native SDK 互通。

在 Firefox 浏览器 v59.0.2 上订阅远端流失败？

该问题是由于浏览器自身限制导致的，建议更新 Firefox 浏览器版本。

调用 `stream.init` 报错 `Media access:SecurityError` ？

请使用 HTTPS 协议。

调用 `stream.init` 报错 `Media access:NotFoundError` ？

找不到指定的媒体流。检查你的麦克风和摄像头是否正常工作。

Safari 浏览器只接收流不发送流时，听不到声音？

如果 Safari 浏览器设置没有打开自动播放，需要在 Stream.play 之前调用方法 navigator.mediaDevices.getUserMedia 获取设备权限，否则会听不到声音。

回声

噪声

音量问题

直播模式下上麦或下麦时音量为什么变化？这个可以避免吗？

听不到声音

卡顿

iOS 蓝牙耳机相关问题

系统电话（包括 CallKit）

VoIP 通话

其他设定

常见问题

卡顿

模糊

黑屏

镜像

无法打开摄像头

显示大头/黑边

为什么旁路直播和旁路直播的录制内容里只听得到声音，却看不到视频?

为什么两个主播进入同一个频道却看不见对方？

为什么设置分辨率为 640 360，实际却为 640 352？

SEI 帧相关问题

声网 SEI 规范

SEI 构成

Q&A

游戏音效问题

进入指挥模式语音频道之前，通过系统的静音键将游戏的音效静音了，但是进入频道之后，为什么游戏的音效就被自动打开了？

打开游戏音效，设置一定的系统音量不改变，进入频道后听到的游戏音效的音量，明显比进入频道之前听到的游戏音效的音量高。

iOS 上开了游戏、游戏语音后，启动语音并立马退出语音房间，然后游戏背景音就变小了。 Android上 是 OK 的。

接入 SDK 后游戏音乐音效与语音相互冲突。

麻将棋牌游戏中，4 个人的背景音乐会被相互串到通话里面 ？

在 app 里播放背景音乐， 然后开加入频道， 这个时候背景音乐音量变化， 当调用了 leaveChannel 之后 背景音乐也没有了。

在播放背景音乐的情况下，join channel 后，听到的背景音乐声音会变小。

onAudioVolumeIndication 获得的音量是 0~255, 有没有什么合适的经验阈值界定说话和没说话?

AMG SDK中 媒体音量系统，在连麦后进入通话音量系统时，原来媒体音量系统播放的背景音效不能调节 ？

iOS 平台

Android 平台

Android 和 iOS 通用的设置

蓝牙耳机为什么没有立体声 ？

设备兼容性问题

Android 与 iPhone 耳机可以兼容吗？

录制SDK

开始录制后，为什么没有录制文件？

录制结束后，为什么检查录制的视频没有声音？

录制结束后，为什么无法播放录制的 MP4 文件？

启用加密模式后，为什么无法播放录制的视频文件，声音也不正常？

当我将加密密码设置为跟客户端一样时，为什么录制仍然不成功？

如何使用 Channel Key?

当启用合流模式之后，为什么只有一个 uid 为 0 的录制文件？

如何对录制文件进行转码?

我可以自己设置录制文件的路径和文件名？

如何保证同时录制的频道数没有超过服务器容量(CPU/内存)?

为什么客户端可以加入频道，而录制端无法加入频道（录制端可以发包，但是却收不到来自 Agora 服务器的包）？

可以指定只录某个用户的音视频么?

如何知道程序是正常退出频道，还是异常退出频道?

录制文件转码后的格式是什么?

使用命令行时，只输入默认的 must 参数，为何启动不了录制程序？

为什么录制并转码完成后的视频，在播放的时候，视频前面会黑一小段？

能录制旋转的视频吗？

录制文件异常

录制文件夹下没有生成录制文件

录制出来的文件时长小于通话时长

录制结束之后只有音频文件，没有视频文件。

录制出来的视频，打开播放黑屏，但是声音正常

录制出来的视频倒置

录制文件出现切片

录制出来的文件，音画不同步怎么办

录制状态异常

录制退出报错

如何判断录制是否崩溃

录制崩溃之后怎么办

Native SDK 与 Web SDK 互通时，在 Native 端录制视频生成的文件是 webm 格式，如何解决？

用户在安卓设备上使用 Chrome 浏览器发起通话，无法与使用 Native 及 Safari 浏览器的用户互通?

H.264 模式下，用户在 macOS 上用 Firefox 浏览器加入通话，打开小流时，获取的分辨率与大流一致？

用户在 macOS 上用 Firefox 浏览器 v59.01 版本加入通话，只能看到本地视频，看不到对方视频？

两台电脑和一台手机互通时，手机出现屏幕卡住的情况，按 home 键也无法退出?

用户在网页端视频过程中，接了个 QQ 电话，再继续网页视频时，就发送不出音频?

Mac 和 Windows 上均使用 Chrome 浏览器通话，如果 Windows 端切换 Wi-Fi，Mac 端画面卡住？

无法加入 channel，报 websocket error，同时会产生类似 ddos 的攻击，短时间巨量的 ws 的连接？

h264_interop 模式下，Firefox 浏览器作为发送端时，接收端切换小流失败？

直播场景中，在 AgoraRTC.createClient({mode: ‘interop’}) 模式下，Web 单主播如果不设置转码推流，就没有视频？

iOS 上开了游戏、游戏语音后，启动语音并立马退出语音房间，然后游戏背景音就变小了。 Android上是 OK 的。

麻将棋牌游戏中，4 个人的背景音乐会被相互串到通话里面？

在 app 里播放背景音乐，然后开加入频道，这个时候背景音乐音量变化，当调用了 leaveChannel 之后背景音乐也没有了。

AMG SDK中媒体音量系统，在连麦后进入通话音量系统时，原来媒体音量系统播放的背景音效不能调节？

蓝牙耳机为什么没有立体声？

调用 `stream.init` 报错 `Media access:SecurityError` ？

调用 `stream.init` 报错 `Media access:NotFoundError` ？