创建 RtcEngine 实例。

RtcEngine 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

注解

• 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
• 调用该方法和 create2 均能创建 RtcEngine 实例。该方法与 create2 的区别在于，create2 支持在创建 RtcEngine 实例时指定访问区域。
• 目前 Agora RTC Native SDK 只支持每个 app 创建一个 RtcEngine 实例。

参数

context	安卓活动 (Android Activity) 的上下文。
appId	Agora 为 app 开发者签发的 App ID，详见获取 App ID。使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 RtcEngine。如需更换 App ID，必须先调用 destroy 销毁当前 RtcEngine，并在 destroy 成功返回后，再调用 create 重新创建 RtcEngine。
handler	io.agora.rtc.IRtcEngineEventHandler 是一个提供了缺省实现的抽象类，SDK 通过该抽象类向 app 报告 SDK 运行时的各种事件

返回

• 方法调用成功，则返回一个 RtcEngine 对象。
• 方法调用失败，则返回错误码。
  • ERR_INVALID_APP_ID(-101)：不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

异常

Exception

调用该方法时可能会发生的异常说明。

创建 RtcEngine 实例。

自从

3.0.0.2

RtcEngine 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

注解

• 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
• 调用该方法和 create1 均能创建 RtcEngine 实例。该方法与 create1 的区别在于，该方法支持在创建 RtcEngine 实例时指定访问区域，详见 RtcEngineConfig 中的 mAreaCode 参数。
• 目前 Agora RTC Native SDK 只支持每个 app 创建一个 RtcEngine 实例。

参数

config

RtcEngine 实例的配置，详见 RtcEngineConfig。

返回

• 方法调用成功，返回一个 RtcEngine 对象。
• 方法调用失败，返回错误码。
  • ERR_INVALID_APP_ID(-101): App ID 无效。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

异常

Exception

调用该方法时可能会发生的异常说明。

销毁 RtcEngine 实例。

该方法释放 Agora SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信，不需要时则将资源释放出来用于其他操作，该方法适用于此类情况。调用 destroy 方法后，你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能，你必须重新调用 create 方法创建一个新的 RtcEngine 实例。

注解

• 该方法为同步调用，需要等待 RtcEngine 实例资源释放后才能执行其他操作，所以我们建议在子线程中调用该方法，避免主线程阻塞。此外，我们不建议在 SDK 的回调中调用 destroy，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。
• 如需在销毁后再次创建 RtcEngine 实例，需要等待 destroy 方法执行结束后再创建实例。

设置频道场景。

SDK 初始化后默认的频道场景为通信场景，你可以调用该方法设置 Agora 频道的使用场景。Agora SDK 会针对不同的使用场景采用不同的优化策略，如通信场景偏好流畅，直播场景偏好画质。

注解

• 为保证实时音视频质量，我们建议相同频道内的用户必须使用同一种频道场景。
• 该方法必须在加入频道前调用，进入频道后无法再设置频道模式。
• 不同的频道场景下，SDK 的默认音频路由和默认视频编码码率是不同的，详见 setDefaultAudioRoutetoSpeakerphone 和 setVideoEncoderConfiguration 中的说明。

参数

profile

频道使用场景： CHANNEL_PROFILE_COMMUNICATION(0)：通信场景。该场景下，频道内所有用户都可以发布和接收音、视频流。适用于语音通话、视频群聊等应用场景。 CHANNEL_PROFILE_LIVE_BROADCASTING(1)：直播场景。该场景有主播和观众两种用户角色，可以通过 setClientRole 设置。主播可以发布和接收音视频流，观众直接接收流。适用于语聊房、视频直播、互动大班课等应用场景。 CHANNEL_PROFILE_GAME(2)：Agora 不推荐使用。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INVALID_ARGUMENT): 参数无效。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

设置直播场景下的用户角色。

调用 setChannelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING) 后，SDK 会默认设置用户角色为观众，你可以调用 setClientRole 设置用户角色为主播。

该方法在加入频道前后均可调用。如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动进行如下操作：

• 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
• 本地触发 onClientRoleChanged。
• 远端触发onUserJoined 或 onUserOffline(USER_OFFLINE_BECOME_AUDIENCE)。

注解

该方法仅适用于直播场景（setChannelProfile 中 profile 设为 CHANNEL_PROFILE_LIVE_BROADCASTING）。

参数

role	直播场景里的用户角色: CLIENT_ROLE_BROADCASTER(1)：主播可以发流也可以收流。如果你在频道中设置该角色，SDK 会自动调用 muteLocalAudioStream(false) 和 muteLocalVideoStream(false)。 CLIENT_ROLE_AUDIENCE(2)：观众只能收流不能发流。如果你在频道中设置该角色，SDK 会自动调用 muteLocalAudioStream(true) 和 muteLocalVideoStream(true)。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -5 (ERR_REFUSED): 调用被拒绝。在多频道场景中，如果你已在一个频道中进行如下设置，则用户在另一个频道内切换角色为主播时会返回该错误码：
    • 调用带 options 参数的 joinChannel，并使用默认设置 publishLocalAudio = true 或 publishLocalVideo = true。
    • 调用 setClientRole，并设置用户角色为主播。
    • 调用 muteLocalAudioStream(false) 或 muteLocalVideoStream(false)。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

设置直播场景下的用户角色。

自从

3.2.0

调用 setChannelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING) 后，SDK 会默认设置用户角色为观众，你可以调用 setClientRole 设置用户角色为主播。

该方法在加入频道前后均可调用。如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动进行如下操作：

• 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
• 本地触发 onClientRoleChanged。
• 远端触发onUserJoined 或 onUserOffline(USER_OFFLINE_BECOME_AUDIENCE)。

注解

• 该方法仅适用于直播场景（setChannelProfile 中 profile 设为 CHANNEL_PROFILE_LIVE_BROADCASTING）。
• 该方法与 setClientRole1 的区别在于，该方法还支持设置用户级别。
  • 用户角色 (role) 确定用户在 SDK 层的权限，包含是否可以发送流、是否可以接收流、是否可以推流到 CDN 等。
  • 用户级别 (level) 需要与角色结合使用，确定用户在其权限范围内，可以操作和享受到的服务级别。例如对于观众，选择接收低延时还是超低延时的视频流。户级别会影响计费。

示例代码

参数

role	直播场景里的用户角色: CLIENT_ROLE_BROADCASTER(1)：主播可以发流也可以收流。如果你在频道中设置该角色，SDK 会自动调用 muteLocalAudioStream(false) 和 muteLocalVideoStream(false)。 CLIENT_ROLE_AUDIENCE(2)：观众只能收流不能发流。如果你在频道中设置该角色，SDK 会自动调用 muteLocalAudioStream(true) 和 muteLocalVideoStream(true)。
options	用户具体设置，包含用户级别，详见 ClientRoleOptions。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INVALID_ARGUMENT): 参数无效。
  • -5 (ERR_REFUSED): 调用被拒绝。在多频道场景中，如果你已在一个频道中进行如下设置，则用户在另一个频道内切换角色为主播时会返回该错误码：
    • 调用带 options 参数的 joinChannel，并使用默认设置 publishLocalAudio = true 或 publishLocalVideo = true。
    • 调用 setClientRole，并设置用户角色为主播。
    • 调用 muteLocalAudioStream(false) 或 muteLocalVideoStream(false)。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

声网提供自定义数据上报和分析服务。

自从

v3.1.0

该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据，每条自定义数据不能超过 256 字节，每个字符串不能超过 100 字节。如需试用该服务，请联系 sales.nosp@m.@ago.nosp@m.ra.io 开通并商定自定义数据格式。

加入频道。

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。使用不同 App ID 的 App 是不能互通的。如果已在通话中，用户必须调用 leaveChannel 退出当前通话，才能进入下一个频道。

成功调用该方加入频道后，本地会触发 onJoinChannelSuccess 回调；通信场景下的用户和直播场景下的主播加入频道后，远端会触发 onUserJoined 回调。

在网络状况不理想的情况下，客户端可能会与 Agora 的服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 onRejoinChannelSuccess 回调。

用户成功加入（切换）频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

警告

请确保用于生成 Token 的 App ID 和 create 方法创建 RtcEngine 对象时用的 App ID 一致。

参数

token	在 app 服务器端生成的用于鉴权的 Token。详见使用 Token 鉴权。
channelName	标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
optionalInfo	（非必选项）预留参数。
optionalUid	（非必选项）用户 ID，32 位无符号整数。建议设置范围：1 到 (232-1)，并保证唯一性。如果不指定（即设为 0），SDK 会自动分配一个，并在 onJoinChannelSuccess 回调方法中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。optionalUid 在 SDK 内部用 32 位无符号整数表示，由于 Java 不支持无符号整数，optionalUid 被当成 32 位有符号整数处理，对于过大的整数，Java 会表示为负数，如有需要可以用 (uid&0xffffffffL) 转换成 64 位整数。频道内每个用户的 UID 必须是唯一的。如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 UID 是不同的。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。
  • -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因：
    • 已经创建了一个同名的 RtcChannel 频道。
    • 已经通过 RtcChannel 加入了一个频道，并在该 RtcChannel 频道中发布了音视频流。由于通过 RtcEngine 加入频道会默认发布音视频流，而 SDK 不支持同时在两个频道发布音视频流，因此会报错。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化，就调用其 API。请确认在调用 API 之前已创建 RtcEngine 对象并完成初始化。

加入频道并设置是否自动订阅音频或视频流。

自从

v3.3.0.

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。使用不同 App ID 的 App 是不能互通的。如果已在通话中，用户必须调用 leaveChannel 退出当前通话，才能进入下一个频道。

成功调用该方法加入频道后，本地会触发 onJoinChannelSuccess 回调；通信场景下的用户和直播场景下的主播加入频道后，远端会触发 onUserJoined 回调。

在网络状况不理想的情况下，客户端可能会与 Agora 的服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 onRejoinChannelSuccess 回调。

警告

• 相比 joinChannel[1/2]，该方法加了 options 参数，用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下，用户订阅频道内所有其他用户的音频流和视频流，因此会产生用量并影响计费。如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。
• 请确保用于生成 Token 的 App ID 和 create 方法创建 RtcEngine 对象时用的 App ID 一致。

参数

token	在 app 服务器端生成的用于鉴权的 Token。详见使用 Token 鉴权。
channelName	标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
optionalInfo	（非必选项）预留参数。
optionalUid	（非必选项）用户 ID，32 位无符号整数。建议设置范围：1 到 (232-1)，并保证唯一性。如果不指定（即设为 0），SDK 会自动分配一个，并在 onJoinChannelSuccess 回调方法中返回，App 需自行维护该返回值，SDK 不对该返回值进行维护。optionalUid 在 SDK 内部用 32 位无符号整数表示，由于 Java 不支持无符号整数，optionalUid 被当成 32 位有符号整数处理，对于过大的整数，Java 会表示为负数，如有需要可以用 (uid&0xffffffffL) 转换成 64 位整数。频道内每个用户的 UID 必须是唯一的。如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 UID 是不同的。
options	频道媒体设置选项：ChannelMediaOptions.

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。
  • -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因：
    • 已经创建了一个同名的 RtcChannel 频道。
    • 已经通过 RtcChannel 加入了一个频道，并在该 RtcChannel 频道中发布了音视频流。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化，就调用其 API。请确认在调用 API 之前已创建 RtcEngine 对象并完成初始化。

快速切换直播频道。

自从

v2.9.0。

当直播频道中的观众想从一个频道切换到另一个频道时，可以调用该方法，实现快速切换。

成功调用该方切换频道后，本地会先收到离开原频道的回调 onLeaveChannel，再收到成功加入新频道的回调 onJoinChannelSuccess。

用户成功加入（切换）频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

注解

该方法仅适用直播频道中的观众用户。

参数

token	在 app 服务端生成的用于鉴权的 Token。详见使用 Token 鉴权。
channelName	标识频道的频道名，最大不超过 64 字节。以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -5(ERR_REFUSED): 调用被拒绝。可能因为用户角色不是观众。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
  • -102(ERR_INVALID_CHANNEL_NAME): 频道名无效。请更换有效的频道名。
  • -113(ERR_NOT_IN_CHANNEL): 用户不在频道内。

快速切换直播频道，并设置是否自动订阅音频流或视频流。

自从

v3.3.0.

当直播频道中的观众想从一个频道切换到另一个频道时，可以调用该方法，实现快速切换。

成功调用该方法切换频道后，本地会先收到离开原频道的回调 onLeaveChannel，再收到成功加入新频道的回调 onJoinChannelSuccess。

注解

• 该方法仅适用直播频道中的观众用户。
• 该方法和 switchChannel[1/2] 的区别在于，该方法加了 options 参数，用于配置终端用户在切换到新的频道时是否自动订阅频道内所有远端音视频流。默认情况下，用户订阅新的频道内所有其他用户的音频流和视频流，因此会产生用量并影响计费。如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。

参数

token	在 app 服务端生成的用于鉴权的 Token。详见使用 Token 鉴权。
channelName	标识频道的频道名，最大不超过 64 字节。以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
options	频道媒体设置选项：ChannelMediaOptions.

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -5(ERR_REFUSED): 调用被拒绝。可能因为用户角色不是观众。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
  • -102(ERR_INVALID_CHANNEL_NAME): 频道名无效。请更换有效的频道名。
  • -113(ERR_NOT_IN_CHANNEL): 用户不在频道内。

离开频道。

离开频道，即挂断或退出通话。

调用 joinChannel 后，必须调用 leaveChannel 结束通话，否则无法开始下一次通话。

不管当前是否在通话中，都可以调用 leaveChannel，没有副作用。

该方法会把会话相关的所有资源释放掉。该方法是异步操作，调用返回时并没有真正退出频道。

成功调用该方法离开频道后，本地会触发 onLeaveChannel 回调；通信场景下的用户和直播场景下的主播离开频道后，远端会触发 onUserOffline 回调。

注解

• 如果你调用了 leaveChannel 后立即调用 destroy 方法，SDK 将无法触发 onLeaveChannel 回调。
• 如果你在旁路推流过程中调用了 leaveChannel 方法， SDK 将自动调用 removePublishStreamUrl 方法。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INALID_ARGUMENT: 参数无效。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

更新 Token。

该方法用于更新 Token。如果启用了 Token 机制，过一段时间后使用的 Token 会失效。以下两种情况下，app 应重新获取 Token，然后调用 renewToken 更新 Token，否则 SDK 无法和服务器建立连接：

• 发生 onTokenPrivilegeWillExpire 回调时。
• onConnectionStateChanged 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。

参数

token

新的 Token。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INALID_ARGUMENT): 参数无效。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

注册本地用户 User Account。

自从

v2.8.0。

该方法为本地用户注册一个 User Account。注册成功后，该 User Account 即可标识该本地用户的身份，用户可以使用它加入频道。

成功注册 User Account 后，本地会触发 onLocalUserRegistered 回调，告知本地用户的 UID 和 User Account。

该方法为可选。如果你希望用户使用 User Account 加入频道，可以选用以下两种方式：

• 先调用 registerLocalUserAccount 方法注册 Account，再调用 joinChannelWithUserAccount 方法加入频道
• 直接调用 joinChannelWithUserAccount 方法加入频道

两种方式的区别在于，提前调用 registerLocalUserAccount，可以缩短使用 joinChannelWithUserAccount 进入频道的时间。

注解

• userAccount 不能为空，否则该方法不生效。
• 请确保在该方法中设置的 userAccount 在频道中的唯一性。
• 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Agora Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

参数

appId	你的项目在 Agora 控制台注册的 App ID
userAccount	用户 User Account。该参数为必填，最大不超过 255 字节，不可填 null。请确保注册的 User Account 的唯一性。以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

使用 User Account 加入频道。

自从

v2.8.0。

该方法允许本地用户使用 User Account 加入频道。成功加入频道后，会触发以下回调：

• 本地：onLocalUserRegistered 和 onJoinChannelSuccess 回调
• 通信场景下的用户和直播场景下的主播加入频道后，远端会依次触发 onUserJoined 和 onUserInfoUpdated 回调

用户成功加入（切换）频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

注解

• 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Agora Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。
• 请确保在使用 String 型用户名前阅读如何使用 String 型用户 ID，了解使用限制及实现方法。

参数

token	在 app 服务端生成的用于鉴权的 Token。详见使用 Token 鉴权。
channelName	标识频道的频道名，最大不超过 64 字节。以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
userAccount	用户 User Account。该参数为必需，最大不超过 255 字节，不可为 null。请确保加入频道的 User Account 的唯一性。以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • ERR_INVALID_ARGUMENT(-2)。
  • ERR_NOT_READY(-3)。
  • ERR_REFUSED(-5)。

使用 User Account 加入频道并设置是否发布或自动订阅音频或视频流

自从

v3.3.0.

该方法允许本地用户使用 User Account 加入频道。 成功加入频道后，会触发以下回调：

• 本地：onLocalUserRegistered 和 onJoinChannelSuccess 回调
• 通信场景下的用户和直播场景下的主播加入频道后，远端会依次触发 onUserJoined 和 onUserInfoUpdated 回调。

注解

• 相比 joinChannelWithUserAccount[1/2]，该方法加了 options 参数，用于配置用户加入频道时是否发布或自动订阅音视频流。 默认情况下，用户发布本地音视频流并自动订阅频道内所有其他用户的音视频流。订阅音视频流会产生用量并影响计费。 如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。
• 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Agora Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。
• 请确保在使用 String 型用户名前阅读如何使用 String 型用户 ID，了解使用限制及实现方法。

参数

token	在 app 服务端生成的用于鉴权的 Token。详见使用 Token 鉴权。
channelName	标识频道的频道名，最大不超过 64 字节。以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
userAccount	用户 User Account。该参数为必需，最大不超过 255 字节，不可为 null。请确保加入频道的 User Account 的唯一性。以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
options	频道媒体设置选项：ChannelMediaOptions.

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • ERR_INVALID_ARGUMENT(-2)
  • ERR_NOT_READY(-3)
  • ERR_REFUSED(-5)

设置 Agora 云代理服务。

当用户防火墙限制 IP 和端口号时，你需要参考《使用云代理》开放相应 IP 和端口号，然后调用该方法开启云代理，并将 proxyType 参数设置为 TRANSPORT_TYPE_UDP_PROXY(1)，即 UDP 协议的云代理。

成功连接云代理后，SDK 会触发 onConnectionStateChanged(CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) 回调。

如果你想关闭已设置的云代理，请调用 setCloudProxy(NONE_PROXY)。如果你想更改已设置的云代理类型，请先调用 setCloudProxy(NONE_PROXY)，再调用 setCloudProxy 并传入你期望的 proxyType 值。

注解

• Agora 推荐你在频道外调用该方法。
• 使用 UDP 协议的云代理时，推流到 CDN 和跨频道媒体流转发功能不可用。

参数

proxyType

云代理类型。该参数为必填参数，如果你不赋值，SDK 会报错。 TRANSPORT_TYPE_NONE_PROXY(0) TRANSPORT_TYPE_UDP_PROXY(1)

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INVALID_ARGUMENT): 传入的参数无效。
  • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

通过 User Account 获取用户信息。

自从

v2.8.0。

远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表， 并在本地触发 onUserInfoUpdated 回调。收到这个回调后，你可以调用该方法，通过传入 User Account 获取包含了指定用户 UID 的 UserInfo 对象。

参数

userAccount	用户 User Account。该参数为必填。
userInfo	[in/out] 标识用户信息的 UserInfo 对象，详见 UserInfo 类 输入值：一个 UserInfo 对象 输出值：一个包含了用户 User Account 和 UID 的 UserInfo 对象

返回

• 0：方法调用成功
• < 0：方法调用失败

通过 UID 获取用户信息。

自从

v2.8.0。

远端用户加入频道后， SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发 onUserInfoUpdated 回调。 收到这个回调后，你可以调用该方法，通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。

参数

uid	用户 ID。该参数为必填。
userInfo	[in/out] 标识用户信息的 UserInfo 对象，详见 UserInfo 类 输入值：一个 UserInfo 对象 输出值：一个包含了用户 User Account 和 UID 的 UserInfo 对象

返回

• 0：方法调用成功
• < 0：方法调用失败

打开与 Web SDK 的互通（仅在直播下适用）。

弃用:

v3.0.0。自 Native SDK 3.0.0 及之后，SDK 自动开启与 Web SDK 的互通，无需调用该方法开启。

该方法打开或关闭与 Agora Web SDK 的互通。如果有用户通过 Web SDK 加入频道，请确保调用该方法，否则 Web 端用户看 Native 端的画面会是黑屏。

该方法仅在直播场景下适用，通信场景下默认互通是打开的。

参数

enabled

是否打开与 Agora Web SDK 的互通： true: 打开互通。 false: （默认）关闭互通。

返回

• 0：方法调用成功。
• <0：方法调用失败。

获取当前网络连接状态。

自从

v2.3.2。

返回

当前的网络连接状态：

• CONNECTION_STATE_DISCONNECTED(1): 网络连接断开。
• CONNECTION_STATE_CONNECTING(2): 建立网络连接中。
• CONNECTION_STATE_CONNECTED(3): 网络已连接。
• CONNECTION_STATE_RECONNECTING(4): 重新建立网络连接中。
• CONNECTION_STATE_FAILED(5): 网络连接失败。

启用音频模块（默认为开启状态）。

注解

• 该方法设置的是音频模块为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
• 该方法开启整个音频模块，响应速度较慢，因此我们建议使用如下方法来控制音频模块：
  • enableLocalAudio：是否启动麦克风采集并创建本地音频流。
  • muteLocalAudioStream：是否发布本地音频流。
  • muteRemoteAudioStream：是否接收并播放远端音频流。
  • muteAllRemoteAudioStreams：是否接收并播放所有远端音频流。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

关闭音频模块。

注解

• 该方法设置的是音频模块为禁用状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
• 该方法关闭整个音频模块，响应速度较慢，因此 Agora 建议使用如下方法来控制音频模块：
  • enableLocalAudio：是否启动麦克风采集并创建本地音频流。
  • muteLocalAudioStream：是否发布本地音频流。
  • muteRemoteAudioStream：是否接收并播放远端音频流。
  • muteAllRemoteAudioStreams：是否接收并播放所有远端音频流。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

禁用频道中的音频功能。

弃用:

该方法已废弃。声网不建议你使用。如果你想禁用频道中的音频功能，请改用 disableAudio 方法。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

启用频道中的音频功能。

弃用:

该方法已废弃。声网不建议你使用。如果你想启用频道中的音频功能，请改用 enableAudio 方法。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置音频编码配置。

注解

• 该方法需要在 joinChannel 之前设置好，joinChannel 后设置不生效。
• 通信和直播场景下，音质（码率）会有网络自适应的调整，通过该方法设置的是一个最高码率。
• 在有高音质需求的场景（例如音乐教学场景）中，建议将 profile 设置为 MUSIC_HIGH_QUALITY (4)，Scenario 设置为 GAME_STREAMING (3)。

参数

profile	设置采样率，码率，编码模式和声道数，详见 AudioProfile。
scenario	设置音频应用场景，详见 AudioScenario。不同的音频场景下，设备的音量类型不同。详见如何区分媒体音量和通话音量。

设置音频高音质选项。

弃用:

该方法已废弃。声网不建议你使用。如果你希望设置音频高音质选项，请改用 setAudioProfile 方法。

该方法设置音频高音质选项。请在加入频道前调用本方法并一次性设置好三个模式。切勿在加入频道后再次调用本方法。

参数

fullband	全频带编解码器（48 kHz 采样率）, 不兼容 1.7.4 以前版本 true: 启用全频带编解码器 false: 禁用全频带编解码器
stereo	立体声编解码器，不兼容 1.7.4 以前版本 true: 启用立体声编解码器 false: 禁用立体声编解码器
fullBitrate	高码率模式，建议仅在纯音频模式下使用 true: 启用高码率模式 false: 禁用高码率模式

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

调节麦克风采集信号音量。

参数

volume

麦克风采集信号音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

返回

• 0: 方法调用成功。
• <0: 方法调用失败。

调节本地播放的所有远端用户信号音量。

注解

• 该方法调节的是本地播放的所有远端用户混音后的音量。
• 从 v2.3.2 开始，静音本地音频需同时调用该方法和 adjustAudioMixingPlayoutVolume 方法，并将 volume 参数设置为 0。

参数

volume

播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

返回

• 0：方法调用成功
• < 0：方法调用失败

调节本地播放的指定远端用户信号音量。

自从

v3.0.0。

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。

注解

• 该方法要在加入频道后调用。
• 该方法调节的是本地播放的指定远端用户混音后的音量。
• 该方法每次只能调整一位远端用户在本地播放的音量。如需调整多位远端用户在本地播放的音量，则需多次调用该方法。

参数

uid	远端用户的 ID。
volume	播放音量，取值范围为 [0,100]。 0：静音。 100：原始音量。

返回

• 0：方法调用成功。
• < 0：方法调用失败。

启用用户音量提示。

该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。启用该方法后，只要频道内有发流用户，SDK 会在加入频道后按设置的时间间隔触发 onAudioVolumeIndication 回调。

参数

interval	指定音量提示的时间间隔： ≤ 0：禁用音量提示功能。 > 0：返回音量提示的间隔，单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒，否则会收不到 onAudioVolumeIndication 回调。
smooth	平滑系数，指定音量提示的灵敏度。取值范围为 [0, 10]，建议值为 3，数字越大，波动越灵敏；数字越小，波动越平滑。
report_vad	是否开启人声检测 true: 开启本地人声检测功能。开启后，onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。 false: （默认）关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外，onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

启用音频质量通知回调。

弃用:

从 v2.4.1 起废弃。

该方法启用音频质量通知回调。一旦启用，onAudioQuality 将被定期触发。

参数

enabled

是否启用音频质量通知回调 true: 启用 false: 禁用（默认）

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

开启/关闭本地音频采集。

当 app 加入频道时，它的语音功能默认是开启的。该方法可以关闭或重新开启本地语音，即停止或重新开始本地音频采集。

该方法不影响接收或播放远端音频流，enableLocalAudio(false) 适用于只听不发的用户场景。

语音功能关闭或重新开启后，会收到回调 onLocalAudioStateChanged ，并报告 LOCAL_AUDIO_STREAM_STATE_STOPPED(0) 或 LOCAL_AUDIO_STREAM_STATE_CAPTURING(1)。

注解

• 该方法与 muteLocalAudioStream 的区别在于：
  • enableLocalAudio 开启或关闭本地语音采集及处理。使用 enableLocalAudio 关闭或开启本地采集后，本地听远端播放会有短暂中断。
  • muteLocalAudioStream 停止或继续发送本地音频流。

参数

enabled

是否开启本地语音。 true:（默认）重新开启本地语音，即开启本地语音采集。 false: 关闭本地语音，即停止本地语音采集。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

取消或恢复发布本地音频流。

自 v3.4.5 起，该方法仅设置用户在 RtcEngine 频道中的音频发布状态。

成功调用该方法后，远端会触发 onUserMuteAudio 回调。

同一时间，本地的音视频流只能发布到一个频道。如果你创建了多个频道，请确保你只在一个频道中调用 muteLocalVideoStream(false)，否则方法会调用失败并返回 -5 (ERR_REFUSED)。

注解

• 该方法不会改变音频采集设备的使用状态。
• 该方法的调用是否生效受 joinChannel 和 setClientRole 方法的影响，详见《设置发布状态》。

参数

muted

是否取消发布本地音频流。 true：取消发布。 false：发布。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。
  • -5 (ERR_REFUSED): 调用被拒绝。

取消或恢复订阅指定远端用户的音频流。

注解

• 该方法需要在加入频道后调用。
• 该方法的推荐设置详见《设置订阅状态》。

参数

uid	指定用户的用户 ID。
muted	是否取消订阅指定远端用户的音频流。 true：取消订阅。 false：（默认）订阅。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

取消或恢复订阅所有远端用户的音频流。

成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的音频流，包括在调用该方法后加入频道的用户的音频流。

注解

• 该方法需要在加入频道后调用。
• 自 v3.3.0 起，该方法包含了 setDefaultMuteAllRemoteAudioStreams 的功能。 Agora 建议不要一起调用 muteAllRemoteAudioStreams 和 setDefaultMuteAllRemoteAudioStreams，否则设置可能会不生效。详见《设置订阅状态》。

参数

muted

是否取消订阅所有远端用户的音频流。 true: 取消订阅。 false:（默认）订阅。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置是否默认接收音频流。

弃用:

该方法自 v3.3.0 起废弃。

默认取消或恢复订阅远端用户的音频流。

该方法需要在加入频道后调用。调用成功后，本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。

注解

取消订阅音频流后，如果需要恢复订阅频道内的远端，可以进行如下操作：

• 如果需要恢复订阅单个用户的音频流，调用 muteRemoteAudioStream(false)，并指定你想要订阅的远端用户 ID。
• 如果想恢复订阅多个用户的音频流，则需要多次调用 muteRemoteAudioStream(false)。

参数

muted

是否默认取消订阅远端用户的音频流： true：默认取消订阅。 false：（默认）默认订阅。

返回

• 0：方法调用成功
• < 0：方法调用失败

启用视频模块。

该方法用于打开视频模式。可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启视频模式，在通话中调用则由音频模式切换为视频模式。调用 disableVideo 方法可关闭视频模式。

成功调用该方法后，远端会触发 onUserEnableVideo(true) 回调。

注解

• 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
• 该方法重置整个引擎，响应速度较慢，因此 Agora 建议使用如下方法来控制视频模块：
  • enableLocalVideo：是否启动摄像头采集并创建本地视频流
  • muteLocalVideoStream：是否发布本地视频流
  • muteRemoteVideoStream：是否接收并播放远端视频流
  • muteAllRemoteVideoStreams：是否接收并播放所有远端视频流

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

关闭视频模块。

该方法用于关闭视频。可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启纯音频模式，在通话中调用则由视频模式切换为纯音频频模式。调用 enableVideo 方法可开启视频模式。

成功调用该方法后，远端会触发 onUserEnableVideo(false) 回调。

注解

• 该方法设置的是内部引擎为禁用状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
• 该方法重置整个引擎，响应速度较慢，因此 Agora 建议使用如下方法来控制视频模块：
  • enableLocalVideo：是否启动摄像头采集并创建本地视频流
  • muteLocalVideoStream：是否发布本地视频流
  • muteRemoteVideoStream：是否接收并播放远端视频流
  • muteAllRemoteVideoStreams：是否接收并播放所有远端视频流

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置视频属性。

弃用:

从 v2.3.2 起废弃。声网不建议你使用。如果你希望设置视频编码属性，请改用 setVideoEncoderConfiguration 方法。

该方法设置视频的编码属性。 该方法在加入频道前后都能调用。 如果用户加入频道后不需要重新设置视频编码属性，则 Agora 建议在 enableVideo 前调用该方法，可以加快首帧出图的时间。

参数

profile	视频属性，详细定义见 Video Profile
swapWidthAndHeight	SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高： true：交换宽和高，交换后视频为 Portrait（竖屏）布局，即宽 < 高 false：（默认）不交换宽和高，视频为 Landscape（横屏）布局，即宽 > 高

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

手动设置视频属性。

弃用:

从 v2.3.2 起废弃。声网不建议你使用。如果你希望设置视频编码属性，请改用 setVideoEncoderConfiguration 方法。

该方法手动设置视频的编码属性。 如果用户加入频道后不需要重新设置视频编码属性，则 Agora 建议在 enableVideo 前调用该方法，可以加快首帧出图的时间。

参数

width	你想要设置的视频宽度，宽 × 高的最大值不超过 1280 × 720。
height	你想要设置的视频高度，宽 × 高的最大值不超过 1280 × 720。
frameRate	你想要设置的视频帧率，最高值不超过 30，如： 5、10、15、24、30 等。
bitrate	你想要设置的视频码率，需要开发者根据想要设置的视频的宽、高和帧率，根据 Bitrate 中的码率参考表，手动推算出合适值。宽和高固定的情况下，码率随帧率的变化而变化： 如选取的帧率为 5 FPS，则推算码率为上表推荐码率除以 2。 如选取的帧率为 15 FPS，则推算码率为上表推荐码率。 如选取的帧率为 30 FPS，则推算码率为上表码率乘以 1.5。 如选取其余帧率，等比例推算即可。 如设置的视频码率超出合理范围，SDK 会自动按照合理区间处理码率。

设置视频编码属性。

自从

v2.3.0。用于替换 setVideoProfile 方法。

该方法设置视频编码属性。每个属性对应一套视频参数，如分辨率、帧率、码率、视频方向等。 所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时，会取最接近最大值的那个值。

如果用户加入频道后不需要重新设置视频编码属性，则 Agora 建议在 enableVideo 前调用该方法，可以加快首帧出图的时间。

参数

config

视频编码属性，详细定义见 VideoEncoderConfiguration

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置摄像头的采集配置。

自从

v2.4.0。

一般的视频通话或直播中，默认由 SDK 自动控制摄像头的输出参数。在如下特殊场景中，默认的参数通常无法满足需求，或可能引起设备性能问题，我们推荐调用该接口设置摄像头的采集配置：

• 使用裸数据自采集接口时，如果 SDK 输出的分辨率和帧率高于 setVideoEncoderConfiguration 中指定的参数，在后续处理视频帧的时候，比如美颜功能时， 会需要更高的 CPU 及内存，容易导致性能问题。在这种情况下，我们推荐将摄像头采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1)，避免性能问题
• 如果没有本地预览功能或者对预览质量没有要求，我们推荐将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1)，以优化 CPU 和内存的资源分配
• 如果用户希望本地预览视频比实际编码发送的视频清晰，可以将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PREVIEW(2)
• 如果用户需要自定义本地采集的视频宽高，请将采集偏好设为 CAPTURER_OUTPUT_PREFERENCE_MANUAL(3)。

注解

请在启动摄像头之前调用该方法，如 joinChannel，enableVideo 或者 enableLocalVideo。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

参数

config

摄像头采集配置，详细定义见 CameraCapturerConfiguration

初始化本地视图。

该方法初始化本地视图并设置本地用户视频显示信息，只影响本地用户看到的视频画面，不影响本地发布视频。 调用该方法绑定本地视频流的显示视窗（View），并设置本地用户视图的渲染模式和镜像模式。

注解

• 请在主线程调用该方法。
• 如果你希望在通话中更新本地用户视图的渲染或镜像模式，请使用 setLocalRenderMode 方法。

参数

local

本地视频显示属性，详细定义见 Video Canvas。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

初始化远端用户视图。

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。

如果 App 不能事先知道对方的用户 ID，可以在 APP 收到 onUserJoined 事件时设置。如果启用了视频录制功能，视频录制服务会做为一个哑客户端加入频道，因此其他客户端也会收到它的 onUserJoined 事件，App 不应给它绑定视图（因为它不会发送视频流），如果 App 不能识别哑客户端，可以在 onFirstRemoteVideoDecoded 事件时再绑定视图。解除某个用户的绑定视图可以把 view 设置为空。退出频道后，SDK 会把远程用户的绑定关系清除掉。

注解

• 请在主线程调用该方法。
• 如果你希望在通话中更新远端用户的渲染或镜像模式，请使用 setRemoteRenderMode 方法。

参数

remote

远端视图属性，详细定义见 Video Canvas。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置本地视频显示模式。

弃用:

v3.0.0。该方法已废弃，请改用 setLocalRenderMode2 方法。

该方法设置本地视频显示模式。App 可以多次调用此方法更改显示模式。

参数

mode	视频显示模式： RENDER_MODE_HIDDEN(1)：优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，多出的视频将被截掉。 RENDER_MODE_FIT(2)：优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同，视窗上未被填满的区域将被涂黑。 RENDER_MODE_ADAPTIVE(3)：已废弃，不再推荐使用。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

更新本地视图显示模式。

自从

v3.0.0。

初始化本地用户视图后，你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面，不影响本地发布视频。

注解

• 请在调用 setupLocalVideo 方法初始化本地视图后，调用该方法。
• 你可以在通话中多次调用该方法，多次更新本地用户视图的显示模式。

参数

renderMode	本地视图的渲染模式。 RENDER_MODE_HIDDEN(1): 优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，多出的视频将被截掉。 RENDER_MODE_FIT(2): 优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同，视窗上未被填满的区域将被涂黑。 RENDER_MODE_ADAPTIVE(3): 已废弃，不再推荐使用。 RENDER_MODE_FILL(4): 视频尺寸进行缩放和拉伸以充满显示视窗。
mirrorMode	本地视图的镜像模式。 VIDEO_MIRROR_AUTO(0): 默认的镜像模式（SDK 决定镜像模式）。如果你使用前置摄像头，默认启动本地视图镜像模式；如果你启用后置摄像头，默认关闭本地视图镜像模式。 VIDEO_MIRROR_MODE_ENABLED(1): 开启镜像模式。 VIDEO_MIRROR_MODE_DISABLED(2): 关闭镜像模式。

返回

• 0：方法调用成功。
• < 0：方法调用失败。

设置远端视频显示模式。

弃用:

v3.0.0. 该方法已废弃，请改用 setRemoteRenderMode2。

该方法设置远端视频显示模式。App 可以多次调用此方法更改显示模式。

参数

uid	远端用户 ID
mode	视频显示模式： RENDER_MODE_HIDDEN(1)：优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，多出的视频将被截掉。 RENDER_MODE_FIT(2)：优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同，视窗上未被填满的区域将被涂黑。 RENDER_MODE_ADAPTIVE(3)：已废弃，不再推荐使用。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

更新远端视图显示模式。

自从

v3.0.0。

初始化远端用户视图后，你可以调用该方法更新远端用户在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

注解

• 请在调用 setupRemoteVideo 方法初始化远端视图后，调用该方法。
• 你可以在通话中多次调用该方法，多次更新远端用户视图的显示模式。

参数

uid	远端用户的 ID。
renderMode	远端用户视图的渲染模式。 RENDER_MODE_HIDDEN(1): 优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，多出的视频将被截掉。 RENDER_MODE_FIT(2): 优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同，视窗上未被填满的区域将被涂黑。 RENDER_MODE_ADAPTIVE(3): 已废弃，不再推荐使用。 RENDER_MODE_FILL(4): 视频尺寸进行缩放和拉伸以充满显示视窗。
mirrorMode	远端用户视图的镜像模式。 VIDEO_MIRROR_AUTO(0): 默认的镜像模式（SDK 决定镜像模式）。SDK 默认关闭远端用户视图的镜像模式。 VIDEO_MIRROR_MODE_ENABLED(1): 开启镜像模式。 VIDEO_MIRROR_MODE_DISABLED(2): 关闭镜像模式。

返回

• 0：方法调用成功。
• < 0：方法调用失败。

创建 RendererView。

该方法创建视频 RendererView，返回 SurfaceView 的类型。View 的操作和布局由 app 管理， Agora SDK 在 app 提供的 View 上进行渲染。显示视频视图必须调用该方法，而不是直接调用 SurfaceView。

如果你需要使用 SurfaceView，请调用本方法；如果你需要使用 TextureView，请调用 CreateTextureView 方法。详见 TextureView 和 SurfaceView 的区别和选择 SurfaceView 或 TextureView。

注解

请在主线程调用该方法。

参数

context

安卓活动 (Android Activity) 的上下文。

返回

SurfaceView

创建 TextureView。

自从

v3.1.0。

该方法创建 TextureView，适用于需要对视频画面进行缩放、旋转和平移的场景，如屏幕共享。View 的操作和布局由 app 管理，SDK 仅在 app 提供的 View 上进行渲染。

如果你需要使用 TextureView，请调用本方法。如果你需要使用 SurfaceView，请调用 CreateRendererView 方法。详见 TextureView 和 SurfaceView 的区别和选择 SurfaceView 或 TextureView。

Agora 推荐你在视频通话和直播场景使用 SurfaceView，在需要对视频画面进行缩放、旋转和平移的场景（如屏幕共享场景）使用 TextureView。

注解

请在主线程调用该方法。

参数

context

安卓活动 (Android Activity) 的上下文。

返回

TextureView

开启视频预览。

该方法用于在进入频道前启动本地视频预览。调用该 API 前，必须：

• 调用 enableVideo 开启视频功能。
• 调用 setupLocalVideo 设置预览窗口及属性。

注解

• 本地预览默认开启镜像功能。
• 使用该方法启用了本地视频预览后，如果直接调用 leaveChannel 退出频道，并不会关闭预览。如需关闭预览，请调用 stopPreview。

返回

• 0：方法调用成功。
• < 0：方法调用失败。

停止视频预览。

注解

请在开启预览后且加入频道前调用该方法。

返回

• 0：方法调用成功
• <0：方法调用失败

开启/关闭本地视频采集。

该方法禁用或重新启用本地视频采集。不影响接收远端视频。

调用 enableVideo 后，本地视频即默认开启。 你可以调用 enableLocalVideo(false) 关闭本地视频采集。关闭后如果想重新开启，则可调用 enableLocalVideo(true)。

成功禁用或启用本地视频采集后，远端会触发 onUserEnableLocalVideo 回调。

注解

该方法设置的是内部引擎为启用或禁用状态，在 leaveChannel 后仍然有效。

参数

enabled

是否启用本地视频： true: 开启本地视频采集和渲染（默认） false: 关闭使用本地摄像头设备。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 false 时，该方法不需要本地有摄像头。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

取消或恢复发布本地视频流。

自 v3.4.5 起，该方法仅设置用户在 RtcEngine 频道中的视频发布状态。

成功调用该方法后，远端会触发 onUserMuteVideo 回调。

同一时间，本地的音视频流只能发布到一个频道。如果你创建了多个频道，请确保你只在一个频道中调用 muteLocalVideoStream(false)， 否则方法会调用失败并返回 -5 (ERR_REFUSED)。

注解

• 该方法不会改变视频采集设备的使用状态。
• 该方法的调用是否生效受 joinChannel 和 setClientRole 方法的影响，详见《设置发布状态》。

参数

muted

是否取消发布本地视频流。 true：取消发布。 false：发布。

返回

• 0：方法调用成功。
• < 0：方法调用失败。
  • -5 (ERR_REFUSED)：调用被拒绝。

取消或恢复订阅指定远端用户的视频流。

注解

• 该方法需要在加入频道后调用。
• 该方法的推荐设置详见《设置订阅状态》。

参数

uid	指定用户的用户 ID。
muted	是否取消订阅指定远端用户的视频流。 true: 取消订阅。 false: （默认）订阅。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

取消或恢复订阅所有远端用户的视频流。

成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的视频流，包括在调用该方法后加入频道的用户的视频流。

注解

• 该方法需要在加入频道后调用。
• 自 v3.3.0 起，该方法包含了 setDefaultMuteAllRemoteVideoStreams 的功能。 Agora 建议不要一起调用 muteAllRemoteVideoStreams 和 setDefaultMuteAllRemoteVideoStreams，否则设置可能会不生效。详见《设置订阅状态》。

参数

muted

是否取消订阅所有远端用户的视频流。 true: 取消订阅。 false:（默认）订阅。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置是否默认接收视频流。

弃用:

该方法自 v3.3.0 起废弃。

默认取消或恢复订阅远端用户的视频流。

该方法需要在加入频道后调用。调用成功后，本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。

注解

取消订阅视频流后，如果需要恢复订阅频道内的远端，可以进行如下操作：

• 如果需要恢复订阅单个用户的视频流，调用 muteRemoteVideoStream(false)，并指定你想要订阅的远端用户 ID。
• 如果想恢复订阅多个用户的视频流，则需要多次调用 muteRemoteVideoStream(false)。

参数

muted

是否默认取消订阅远端用户的视频流： true：默认取消订阅。 false：（默认）默认订阅。

返回

• 0：方法调用成功
• < 0：方法调用失败

开启本地美颜功能，并设置美颜效果选项。

自从

v2.4.0。

注解

• 该方法需要在 enableVideo 之后调用。
• 该方法仅适用于 Android 4.4 及以上版本。

参数

enabled	是否开启美颜功能： true：开启 false：（默认）关闭
options	美颜选项，详细定义见 BeautyOptions

返回

• 0：方法调用成功
• < 0：方法调用失败
  • ERR_NOT_SUPPORTED(4)：当前设备版本低于 Android 4.4，不支持该操作。

开启/关闭虚拟背景。（beta 功能）

自从

v3.5.0

开启虚拟背景功能后，你可以使用自定义的背景图替代本地用户原来的背景图。 替换后，频道内所有用户都能看到自定义的背景图。你可以从 onVirtualBackgroundSourceEnabled 回调了解虚拟背景是否成功开启和相应的出错原因。

注解

• 调用该方法前，请确保你已经将 libagora_segmentation_extension.so 动态库集成到项目文件中。
• 请在 enableVideo 后调用该方法。
• 该功能对设备性能要求较高，Agora 推荐你在搭载如下芯片的设备上使用：
  • 骁龙 700 系列 750G 及以上
  • 骁龙 800 系列 835 及以上
  • 天玑 700 系列 720 及以上
  • 麒麟 800 系列 810 及以上
  • 麒麟 900 系列 980 及以上
• Agora 建议你在满足如下条件的场景中使用该功能：
  • 使用高清摄像设备、摄像环境光照均匀。
  • 摄像画面中，物件较少，用户的人像为半身人像且基本无遮挡，背景色较单一且与用户着装颜色不同。

参数

enabled	设置是否开启虚拟背景： true：开启。 false：关闭。
backgroundSource	自定义的背景图。详见 VirtualBackgroundSource。 Note：为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配，SDK 会在保证自定义背景图内容不变形的前提下，对自定义背景图进行缩放和裁剪。

返回

• 0：方法调用成功
• < 0：方法调用失败

设置默认的音频路由。

如果 SDK 默认的音频路由（见《设置音频路由》）无法满足你的需求，你可以调用该方法切换默认的音频路由。 成功切换音频路由后，SDK 会触发 onAudioRouteChanged 回调提示音频路由已更改。

注解

• 该方法需要在 joinChannel 前调用。如需在加入频道后切换音频路由，请调用 setEnableSpeakerphone。
• 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备，则该方法的设置无效，音频只会通过外接设备播放。 当有多个外接设备时，音频会通过最后一个接入的设备播放。

参数

defaultToSpeaker

设置默认的音频路由： true：默认的音频路由为扬声器。 false：默认的音频路由为听筒。

返回

• 0：方法调用成功
• < 0：方法调用失败

开启/关闭扬声器播放。

如果 SDK 默认的音频路由（见《设置音频路由》）或 setDefaultAudioRoutetoSpeakerphone 的设置无法满足你的需求，你可以调用 setEnableSpeakerphone 切换当前的音频路由。 成功切换音频路由后，SDK 会触发 onAudioRouteChanged 回调提示音频路由已更改。

该方法只设置用户在当前频道内使用的音频路由，不会影响 SDK 默认的音频路由。 如果用户离开当前频道并加入新的频道，则用户还是会使用 SDK 默认的音频路由。

注解

• 该方法需要在 joinChannel 后调用。
• 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备，则该方法的设置无效，音频只会通过外接设备播放。当有多个外接设备时，音频会通过最后一个接入的设备播放。

参数

enabled

设置是否开启扬声器播放 true：开启。音频路由为扬声器。 false：关闭。音频路由为听筒。

返回

• 0：方法调用成功
• < 0：方法调用失败

检查扬声器状态启用状态。

该方法检查扬声器是否已开启。

注解

该方法在加入频道前后都能调用。

返回

• true：扬声器已开启，语音会输出到扬声器
• false：扬声器未开启，语音会输出到非扬声器（听筒，耳机等）

开启耳返功能。

该方法打开或关闭耳返功能。

注解

• 用户必须使用有线耳机才能听到耳返效果。
• 自 v3.1.0 起，你可以在以下 Android 设备中体验更低的耳返延迟：
  • OPPO Reno4 Pro 5G
  • OPPO Reno4 5G

参数

enabled

true: 开启耳返功能 false: （默认）关闭耳返功能

返回

• 0：方法调用成功
• < 0：方法调用失败

设置耳返音量。

注解

用户必须使用有线耳机才能听到耳返效果。

参数

volume

设置耳返音量，取值范围在 0 到 100 间。默认值为 100。

返回

• 0：方法调用成功
• < 0：方法调用失败

使用外部音频设备。

弃用:

该方法已废弃。声网不建议你使用。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置本地语音音调。

该方法改变本地说话人声音的音调。

参数

pitch

语音频率。可以在 [0.5, 2.0] 范围内设置。取值越小，则音调越低。默认值为 1.0，表示不需要修改音调。

返回

• 0：方法调用成功
• < 0：方法调用失败

设置本地语音音效均衡。

参数

bandFrequency	频谱子带索引，取值范围是 [0-9]，分别代表 10 个频带，对应的中心频率是 [31，62，125，250，500，1k，2k，4k，8k，16k] Hz
bandGain	每个 band 的增益，单位是 dB，每一个值的范围是 [-15，15]，默认值为 0

返回

• 0：方法调用成功
• < 0：方法调用失败

设置本地音效混响。

注解

SDK 在 v3.2.0 版本中提供一个使用更为简便的方法 setAudioEffectPreset，直接实现流行、R&B、KTV 等预置的混响效果。

参数

reverbKey	混响音效 Key。该方法共有 5 个混响音效 Key，分别如 value 栏列出。
value	各混响音效 Key 所对应的值： AUDIO_REVERB_DRY_LEVEL(0)：原始声音强度，即所谓的 dry signal，取值范围 [-20, 10]，单位为 dB AUDIO_REVERB_WET_LEVEL(1)：早期反射信号强度，即所谓的 wet signal，取值范围 [-20, 10]，单位为 dB AUDIO_REVERB_ROOM_SIZE(2)：所需混响效果的房间尺寸，一般房间越大，混响越强，取值范围 [0, 100]，单位为 dB AUDIO_REVERB_WET_DELAY(3)：Wet signal 的初始延迟长度，取值范围 [0, 200]，单位为毫秒 AUDIO_REVERB_STRENGTH(4)：混响持续的强度，取值范围为 [0, 100]

返回

• 0：方法调用成功
• < 0：方法调用失败

设置本地语音变声、美音或语聊美声效果。

弃用:

该方法从 v3.2.0 起废弃，请改用以下方法：

• setAudioEffectPreset：音效。
• setVoiceBeautifierPreset：美声效果。
• setVoiceConversionPreset：变声效果。

自从

v2.4.0。

该方法在频道内外均可调用。

通信场景下的用户或直播场景下的主播均可调用该方法为本地语音设置以下效果。成功设置以后，频道内的所有用户均可听到声音效果。

• 变声效果：枚举值以 VOICE_CHANGER 为前缀。效果包括老男孩、小男孩、小女孩、猪八戒、空灵和绿巨人，通常用于语聊场景。
• 美音效果：枚举值以 VOICE_BEAUTY 为前缀。效果包括浑厚、低沉、圆润、假音、饱满、清澈、高亢、嘹亮和空旷，通常用于语聊和唱歌场景。
• 语聊美声效果：枚举值以 GENERAL_BEAUTY_VOICE 为前缀。效果包括磁性（男）、清新（女）和活力（女），通常用于语聊场景。该功能主要细化了男声和女声各自的特点。

注解

• 为达到更好的声音效果，Agora 推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)。
• 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含人声和音乐的音频数据。
• 该方法不能与 setLocalVoiceReverbPreset 方法一同使用，否则先调的方法会不生效。更多注意事项，详见《设置人声效果》。

参数

voiceChanger

本地语音的变声、美音或语聊美声效果选项： VOICE_CHANGER_OFF: （默认）原声，即关闭本地语音的变声、美音或语聊美声效果。 VOICE_CHANGER_OLDMAN: 变声：老男孩 VOICE_CHANGER_BABYBOY: 变声：小男孩 VOICE_CHANGER_BABYGIRL: 变声：小女孩 VOICE_CHANGER_ZHUBAJIE: 变声：猪八戒 VOICE_CHANGER_ETHEREAL: 变声：空灵 VOICE_CHANGER_HULK: 变声：绿巨人 VOICE_BEAUTY_VIGOROUS: 美音：浑厚 VOICE_BEAUTY_DEEP: 美音：低沉 VOICE_BEAUTY_MELLOW: 美音：圆润 VOICE_BEAUTY_FALSETTO: 美音：假音 VOICE_BEAUTY_FULL: 美音：饱满 VOICE_BEAUTY_CLEAR: 美音：清澈 VOICE_BEAUTY_RESOUNDING: 美音：高亢 VOICE_BEAUTY_RINGING: 美音：嘹亮 VOICE_BEAUTY_SPACIAL: 美音：空旷 GENERAL_BEAUTY_VOICE_MALE_MAGNETIC: 语聊美声：磁性（男）。此枚举为男声定制化效果，不适用于女声。如女声使用此音效设置，则音频可能会产生失真。 GENERAL_BEAUTY_VOICE_FEMALE_FRESH: 语聊美声：清新（女）。此枚举为女声定制化效果，不适用于男声。如男声使用此音效设置，则音频可能会产生失真。 GENERAL_BEAUTY_VOICE_FEMALE_VITALITY: 语聊美声：活力（女）。此枚举为女声定制化效果，不适用于男声。如男声使用此音效设置，则音频可能会产生失真。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置本地语音混响（含虚拟立体声效果）。

弃用:

该方法从 v3.2.0 起废弃，请改用 setAudioEffectPreset 或 setVoiceBeautifierPreset。

自从

v2.4.0。

该方法在频道内外均可调用。

通信场景下的用户或直播场景下的主播均可调用该方法设置本地语音混响。成功设置以后，频道内的所有用户均可听到声音效果。

注解

• 当使用以 AUDIO_REVERB_FX 为前缀的枚举值时，请确保在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)，否则该方法设置无效。
• 当使用 AUDIO_VIRTUAL_STEREO 时，Agora 推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)。
• 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含人声和音乐的音频数据。
• 该方法不能与 setLocalVoiceChanger 方法一同使用，否则先调的方法会不生效。更多注意事项，详见《设置人声效果》。

参数

preset

本地语音混响选项。为达到更好的混响效果，Agora 推荐使用以 AUDIO_REVERB_FX 为前缀的枚举值。 AUDIO_REVERB_OFF: （默认）原声，即关闭本地语音混响。 AUDIO_REVERB_POPULAR: 流行 AUDIO_REVERB_RNB: R&B AUDIO_REVERB_ROCK: 摇滚 AUDIO_REVERB_HIPHOP: 嘻哈 AUDIO_REVERB_VOCAL_CONCERT: 演唱会 AUDIO_REVERB_KTV: KTV AUDIO_REVERB_STUDIO: 录音棚 AUDIO_REVERB_FX_KTV: KTV（增强版） AUDIO_REVERB_FX_VOCAL_CONCERT: 演唱会（增强版） AUDIO_REVERB_FX_UNCLE: 大叔 AUDIO_REVERB_FX_SISTER: 小姐姐 AUDIO_REVERB_FX_STUDIO: 录音棚（增强版） AUDIO_REVERB_FX_POPULAR: 流行（增强版） AUDIO_REVERB_FX_RNB: R&B（增强版） AUDIO_REVERB_FX_PHONOGRAPH: 留声机 AUDIO_VIRTUAL_STEREO: 虚拟立体声。虚拟立体声是指将单声道的音轨渲染出立体声的效果，使频道内所有用户听到有空间感的声音效果。为达到更好的虚拟立体声效果，Agora 推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置 SDK 预设的人声音效。

自从

v3.2.0

调用该方法可以为本地发流用户设置 SDK 预设的人声音效，且不会改变原声的性别特征。设置音效后，频道 内所有用户都能听到该效果。

根据不同的场景，你可以为用户设置不同的音效，各音效的适用场景可参考《设置人声效果》。

为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)。

注解

• 该方法在加入频道前后都能调用。
• 请勿将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD(1)，否则该方法不生效。
• 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。
• 如果调用该方法并设置除 ROOM_ACOUSTICS_3D_VOICE 或 PITCH_CORRECTION 外的枚举，请勿再调用 setAudioEffectParameters，否则该方法设置的效果会被覆盖。
• 调用该方法后，Agora 不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  • setVoiceBeautifierPreset
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset

参数

preset

预设的音效选项。 AUDIO_EFFECT_OFF ROOM_ACOUSTICS_KTV ROOM_ACOUSTICS_VOCAL_CONCERT ROOM_ACOUSTICS_STUDIO ROOM_ACOUSTICS_PHONOGRAPH ROOM_ACOUSTICS_VIRTUAL_STEREO ROOM_ACOUSTICS_SPACIAL ROOM_ACOUSTICS_ETHEREAL ROOM_ACOUSTICS_3D_VOICE VOICE_CHANGER_EFFECT_UNCLE VOICE_CHANGER_EFFECT_OLDMAN VOICE_CHANGER_EFFECT_BOY VOICE_CHANGER_EFFECT_SISTER VOICE_CHANGER_EFFECT_GIRL VOICE_CHANGER_EFFECT_PIGKING VOICE_CHANGER_EFFECT_HULK STYLE_TRANSFORMATION_RNB STYLE_TRANSFORMATION_POPULAR PITCH_CORRECTION

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置 SDK 预设的美声效果。

自从

v3.2.0

调用该方法可以为本地发流用户设置 SDK 预设的人声美化效果。设置美声效果后，频道内所有用户都能听到该效果。根据不同的场景，你可以为用户设置不同的美声效果，各美声效果的适用场景可参考《设置人声效果》。

为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)，并将 profile 设为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)。

注解

• 该方法在加入频道前后都能调用。
• 请勿将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD(1)，否则该方法不生效。
• 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。
• 调用该方法后，Agora 不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset

参数

preset

预设的美声效果选项： VOICE_BEAUTIFIER_OFF CHAT_BEAUTIFIER_MAGNETIC CHAT_BEAUTIFIER_FRESH CHAT_BEAUTIFIER_VITALITY TIMBRE_TRANSFORMATION_VIGOROUS TIMBRE_TRANSFORMATION_DEEP TIMBRE_TRANSFORMATION_MELLOW TIMBRE_TRANSFORMATION_FALSETTO TIMBRE_TRANSFORMATION_FULL TIMBRE_TRANSFORMATION_CLEAR TIMBRE_TRANSFORMATION_RESOUNDING TIMBRE_TRANSFORMATION_RINGING

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置 SDK 预设的变声效果。

自从

v3.3.1

调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后，频道内所有用户都能听到该效果。根据不同的场景，你可以为用户设置不同的变声效果，各变声效果的适用场景可参考《设置人声效果》。

为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)，并将 profile 设为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)。

注解

• 该方法在加入频道前后都能调用。
• 请勿将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD(1)，否则该方法不生效。
• 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。
• 调用该方法后，Agora 不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setVoiceBeautifierPreset
  • setVoiceBeautifierParameters
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb

参数

preset

预设的变声效果选项： VOICE_CONVERSION_OFF VOICE_CHANGER_NEUTRAL VOICE_CHANGER_SWEET VOICE_CHANGER_SOLID VOICE_CHANGER_BASS

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置 SDK 预设人声音效的参数。

自从

v3.2.0

调用该方法可以对本地发流用户进行如下设置：

• 3D 人声音效：设置 3D 人声音效的环绕周期。
• 电音音效：设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效，Agora 推荐你将基础调式和主音音高配置选项与应用的 UI 元素绑定。

设置后，频道内所有用户都能听到该效果。

注解

• 该方法在加入频道前后都能调用。
• 为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)。
• 请勿将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD(1)，否则该方法不生效。
• 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。
• 调用该方法后，Agora 不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  • setAudioEffectPreset
  • setVoiceBeautifierPreset
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset

参数

preset	SDK 预设的音效： 3D 人声音效：ROOM_ACOUSTICS_3D_VOICE 你需要在使用该枚举前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)，否则该枚举设置无效。 启用 3D 人声后，用户需要使用支持双声道的音频播放设备才能听到预期效果。 电音音效：PITCH_CORRECTION。为获取更好的人声效果，Agora 建议你在使用该枚举前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)。
param1	如果 preset 设为 ROOM_ACOUSTICS_3D_VOICE，则 param1 表示 3D 人声音效的环绕周期。取值范围为 [1,60]，单位为秒。默认值为 10，表示人声会 10 秒环绕 360 度。 如果 preset 设为 PITCH_CORRECTION，则 param1 表示电音音效的基础调式。可设为如下值： 1: （默认）自然大调。 2: 自然小调。 3: 和风小调。
param2	你需要将 param2 设置为 0。 如果preset设为PITCH_CORRECTION，则param2表示电音音效的主音音高。可设为如下值： -1: A 调 -2: A# 调 -3: B 调 -4: （默认）C 调 -5: C# 调 -6: D 调 -7: D# 调 -8: E 调 -9: F 调 -10: F# 调 -11: G 调 -12`: G# 调

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置 SDK 预设美声效果的参数。

自从

3.3.0.

调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后，频道内所有用户都能听到该效果。

为获取更好的人声效果，Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)，并将 profile 设为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)。

注解

• 该方法在加入频道前后都能调用。
• 请勿将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD(1)，否则该方法不生效。
• 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。
• 调用该方法后，Agora 不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setVoiceBeautifierPreset
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceConversionPreset

参数

preset	SDK 预设的音效： SINGING_BEAUTIFIER: 歌唱美声。
param1	歌声的性别特征： 1: 男声。 2: 女声。
param2	歌声的混响效果： 1: 歌声在小房间的混响效果。 2: 歌声在大房间的混响效果。 3: 歌声在大厅的混响效果。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

开启或关闭 AI 降噪模式。

自从

v3.3.0

SDK 默认开启传统降噪模式，以消除大部分平稳噪声。如果你还需要消除非平稳噪声，Agora 推荐你按如下步骤开启 AI 降噪模式：

• 1. 确保已集成 libagora_ai_denoise_extension.so。
• 2. 调用 enableDeepLearningDenoise(true)。

AI 降噪模式对设备性能有要求。只有在设备性能良好的情况下，SDK 才会成功开启 AI 降噪模式。

成功开启 AI 降噪模式后，如果 SDK 检测到当前设备的性能不足，SDK 会自动关闭 AI 降噪模式，并开启传统降噪模式。

在频道内，如果你调用了 enableDeepLearningDenoise(false) 或 SDK 自动关闭了 AI 降噪模式，当你需要重新开启 AI 降噪模式时，你需要先调用 leaveChannel，再调用 enableDeepLearningDenoise(true)。

注解

• 该方法需要动态加载 libagora_ai_denoise_extension.so，所以 Agora 推荐在加入频道前调用该方法。
• 该方法对人声的处理效果最佳，Agora 不推荐调用该方法处理含音乐的音频数据。

参数

enabled

是否开启 AI 降噪模式： true:（默认）开启。 false: 关闭。

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • -157 (ERR_MODULE_NOT_FOUND): 未集成 AI 降噪库。

开启/关闭远端用户的语音立体声。

自从

v2.4.0。

如果想调用 setRemoteVoicePosition 实现听声辨位的功能，请确保在调用 joinChannel 方法前调用该方法。

参数

enabled

是否开启远端用户语音立体声： true：开启 false：（默认）关闭

返回

• 0：方法调用成功
• < 0：方法调用失败

设置远端用户声音的空间位置和音量，方便本地用户听声辨位。

自从

v2.4.0。

用户通过调用该接口，设置远端用户声音出现的位置，左右声道的声音差异会让用户产生声音的方位感，从而判断出远端用户的实时位置。在多人在线游戏场景，如吃鸡游戏中，该方法能有效增加游戏角色的方位感，模拟真实场景。

注解

• 该方法需要在加入频道后调用。
• 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声。
• 为获得最佳听觉体验，我们建议用户佩戴有线耳机。

参数

uid	远端用户的 ID
pan	设置远端用户声音出现的位置，取值范围为 [-1.0, 1.0]： 0.0：（默认）声音出现在正前方 -1.0：声音出现在左边 1.0：声音出现在右边
gain	设置远端用户声音的音量，取值范围为 [0.0, 100.0]，默认值为 100.0，表示该用户的原始音量。取值越小，则音量越低

返回

• 0：方法调用成功
• < 0：方法调用失败

开始播放音乐文件及混音。

弃用:

自 v3.4.0 废弃，请改用 startAudioMixing[2/2]。

该方法指定本地或在线音频文件来和麦克风采集的音频流进行混音或替换。替换是指用音频文件替换麦克风采集的音频流。该方法可以选择是否让对方听到本地播放的音频，并指定循环播放的次数。 成功调用该方法后，本地会触发 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调。播放结束后，会收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_STOPPED) 回调。

注解

• 如需调用该方法，请确保使用 Android 4.2 或以上设备，且 API Level ≥ 16。
• 如果播放的是在线音乐文件，请确保重复调用该 API 的间隔超过 100 ms，否则 SDK 会返回 MEDIA_ENGINE_AUDIO_ERROR_MIXING_TOO_FREQUENT(702) 警告码，表示音乐文件打开过于频繁。
• 如果播放的是在线音乐文件，Agora 建议不要使用重定向地址。重定向地址在某些机型上可能会出现无法打开的情况。
• 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 MEDIA_ENGINE_AUDIO_ERROR_MIXING_OPEN(701)。
• 如果在模拟器上使用该 API，暂时只支持存放在 /sdcard/ 中的 mp3 文件。
• 为避免阻塞，自 v3.4.5 起，该方法由同步调用改为异步调用。

参数

filePath	文件路径，需精确到文件名及后缀。 支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。**Note** 通过绝对路径访问本地文件可能会遇到权限问题，Agora 推荐使用 URI 地址访问本地文件。 例如："content://com.android.providers.media.documents/document/audio%3A14441"。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。
loopback	true：只有本地可以听到混音或替换后的音频流 false：本地和对方都可以听到混音或替换后的音频流
replace	true：只推动设置的本地音频文件或者线上音频文件，不传输麦克风收录的音频 false：音频文件内容将会和麦克风采集的音频流进行混音
cycle	音频文件循环播放的次数： ≥ 0: 播放次数。例如，0 表示不播放；1 表示播放 1 次。 -1：无限循环。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。
  • WARN_AUDIO_MIXING_OPEN_ERROR(701): 如果指定播放的音频文件不存在，或打开在线文件流后 5 秒内未收到网络流的数据包，则 SDK 会认为媒体文件不可访问，并返回该警告。

开始播放音乐文件。

自从

v3.4.0

该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。 成功播放音乐文件后，本地会触发 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY, AUDIO_MIXING_REASON_STARTED_BY_USER) 回调。 播放结束后，本地会触发 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_STOPPED, AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED) 回调。

注解

• 如需调用该方法，请确保使用 Android 4.2 或以上设备，且 API Level ≥ 16。
• 如果播放的是在线音乐文件，Agora 建议不要使用重定向地址。重定向地址在某些机型上可能会出现无法打开的情况。
• 如果在模拟器上使用该 API，暂时只支持存放在 /sdcard/ 中的 mp3 文件。
• 该方法需要在加入频道后调用。如需多次调用 startAudioMixing，请确保调用间隔大于 500 ms。
• 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，则 SDK 会报告 WARN_AUDIO_MIXING_OPEN_ERROR(701)。
• 为避免阻塞，自 v3.4.5 起，该方法由同步调用改为异步调用。

参数

filePath	文件路径，需精确到文件名及后缀。 支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note 通过绝对路径访问本地文件可能会遇到权限问题，Agora 推荐使用 URI 地址访问本地文件。 例如："content://com.android.providers.media.documents/document/audio%3A14441"。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。
loopback	是否只在本地播放音乐文件： true: 只在本地播放音乐文件，只有本地用户能听到音乐。 false: 将本地播放的音乐文件发布至远端，本地用户和远端用户都能听到音乐。
replace	是否用音乐文件替换麦克风采集的音频： true: 替换。用户只能听到音乐。 false: 不替换。用户可以听到音乐和麦克风采集的音频。
cycle	音乐文件的播放次数。 ≥ 0: 播放次数。例如，0 表示不播放；1 表示播放 1 次。 -1: 无限循环播放。
startPos	音乐文件的播放位置，单位为毫秒。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

停止播放音乐文件及混音。

该方法停止播放伴奏。请在频道内调用该方法。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

暂停播放音乐文件及混音。

该方法暂停播放伴奏。请在频道内调用该方法。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

恢复播放音乐文件及混音。

该方法恢复混音，继续播放伴奏。请在频道内调用该方法。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

调节音乐文件的播放音量。

该方法调节混音里伴奏在本端和远端播放的音量大小。

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调后调用该方法。

注解

调用该方法不影响调用 playEffect 播放音效文件的音量。

参数

volume

伴奏音量范围为 0~100。默认 100 为原始文件音量。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

调节音乐文件的本地播放音量。

自从

v2.3.2。

该方法调节混音里音乐文件在本端播放的音量大小。

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调后调用该方法。

参数

volume

伴奏音量范围为 0~100。默认 100 为原始文件音量。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

调节音乐文件的远端播放音量。

自从

v2.3.2。

该方法调节混音里音乐文件在远端播放的音量大小。

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调后调用该方法。

参数

volume

伴奏音量范围为 0~100。默认 100 为原始文件音量。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

获取音乐文件的本地播放音量。

自从

v2.4.1。

该方法获取音乐文件的本地播放音量。该接口可以方便开发者排查音量相关问题。

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调后调用该方法。

返回

• 方法调用成功则返回音量值，范围为 [0, 100]。
• < 0：方法调用失败。

获取音乐文件的远端播放音量。

自从

v2.4.1。

该方法获取音乐文件的远端播放音量。该接口可以方便开发者排查音量相关问题。

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调后调用该方法。

返回

• 方法调用成功则返回音量值，范围为 [0, 100]。
• < 0：方法调用失败。

获取音乐文件的时长。

弃用:

自 v3.4.0 废弃。

该方法获取音乐文件时长，单位为毫秒。请在频道内调用该方法。如果返回值 < 0，表明调用失败。

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调后调用该方法。

返回

• 方法调用成功，并返回伴奏时长。
• < 0：方法调用失败。

获取音乐文件的播放进度。

该方法获取当前伴奏播放进度，单位为毫秒。

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调后调用该方法。

注解

如需多次调用 getAudioMixingCurrentPosition，请确保调用间隔大于 500 ms。

返回

• 方法调用成功并返回伴奏播放进度。
• < 0：方法调用失败。

设置音乐文件的播放位置。

该方法可以设置音频文件的播放位置，这样你可以根据实际情况播放文件，而不是非得从头到尾播放一个文件。

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调后调用该方法。

参数

pos	整数。进度条位置，单位为毫秒。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

调整本地播放的音乐文件的音调。

自从

3.0.1

本地人声和播放的音乐文件混音时，调用该方法可以仅调节音乐文件的音调。

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调后调用该方法。

参数

pitch

按半音音阶调整本地播放的音乐文件的音调，默认值为 0，即不调整音调。取值范围为 [-12,12]，每相邻两个值的音高距离相差半音。取值的绝对值越大，音调升高或降低得越多。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

获取 IAudioEffectManager 类，以管理音效文件。

返回

IAudioEffectManager

开始客户端录音。

弃用:

从 v2.9.1 起废弃。请改用 startAudioRecording[3/3]。

Agora SDK 支持通话过程中在客户端进行录音。该方法录制频道内所有用户的音频，并生成一个包含所有用户声音的录音文件，录音文件格式可以为：

• .wav：文件大，音质保真度高。
• .aac：文件小，有一定的音质保真度损失。

该方法的录制采样率固定为 32 kHz。

该接口需在加入频道之后调用。如果调用 leaveChannel 时还在录音，录音会自动停止。

参数

filePath	录音文件的本地保存路径，由用户自行指定，需精确到文件名及格式，例如：/sdcard/emulated/0/audio.aac。请确保目录存在且可写。
quality	录音音质： AUDIO_RECORDING_QUALITY_LOW(0)：低音质。 AUDIO_RECORDING_QUALITY_MEDIUM(1)：中音质。 AUDIO_RECORDING_QUALITY_HIGH(2)：高音质。

返回

• 0：方法调用成功
• < 0：方法调用失败
  • ERR_REFUSED(-5)：无法启动测试，可能没有成功初始化。

开始客户端录音。

自从

v2.9.1

弃用:

从 v3.4.0 起废弃。请改用 startAudioRecording[3/3]。

Agora SDK 支持通话过程中在客户端进行录音。调用该方法后，你可以录制频道内所有用户的音频，并得到一个包含所有用户声音的录音文件。录音文件格式可以为：

• .wav：文件大，音质保真度较高。
• .aac：文件小，音质保真度较低。

注解

• 请确保你在该方法中指定的路径存在并且可写。
• 该接口需要在 joinChannel 之后调用。如果调用 leaveChannel 时还在录音，录音会自动停止。
• 为保证录音效果，当 sampleRate 设为 44.1 kHz 或 48 kHz 时，建议将 quality 设为 AUDIO_RECORDING_QUALITY_MEDIUM 或 AUDIO_RECORDING_QUALITY_HIGH。

参数

filePath	录音文件在本地保存的绝对路径，由用户自行制定，需精确到文件名及格式，例如：/dir1/dir2/dir3/audio.aac。
sampleRate	录音采样率 (Hz)，可以设置为以下值： 16000 （默认）32000 44100 48000
quality	录音音质： AUDIO_RECORDING_QUALITY_LOW(0)：低音质 AUDIO_RECORDING_QUALITY_MEDIUM(1)：中音质 AUDIO_RECORDING_QUALITY_HIGH(2)：高音质

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。
  • ERR_REFUSED(-5)：无法启动测试，可能没有成功初始化。

开始客户端录音。

自从

v3.4.0

Agora SDK 支持通话过程中在客户端进行录音。调用该方法后，你可以录制频道内用户的音频，并得到一个录音文件。录音文件格式可以为:

• WAV: 音质保真度较高，文件较大。例如，采样率为 32000 Hz，录音时长为 10 分钟的文件大小约为 73 M。
• AAC: 音质保真度较低，文件较小。例如，采样率为 32000 Hz，录音音质为 AUDIO_RECORDING_QUALITY_MEDIUM，录音时长为 10 分钟的文件大小约为 2 M。

一旦用户离开频道，录音会自动停止。

注解

该方法需要在加入频道后调用。

参数

config

录音配置。详见 AudioRecordingConfiguration。

返回

• 0: 方法调用成功
• < 0: 方法调用失败

停止客户端录音。

返回

• 0： 方法调用成功
• <0： 方法调用失败
  • ERR_REFUSED(-5)：无法启动测试，可能没有成功初始化

开始语音通话回路测试。

弃用:

从 v2.4.0 起废弃。声网建议使用 startEchoTest 方法开始语音回路测试。 该方法启动语音通话测试，目的是测试系统的音频设备（耳麦、扬声器等）和网络连接是否正常。在测试过程中，用户先说一段话，在 10 秒后，声音会回放出来。如果 10 秒后用户能正常听到自己刚才说的话，就表示系统音频设备和网络连接都是正常的。

注解

• 调用 startEchoTest 后必须调用 stopEchoTest 以结束测试，否则不能进行下一次回声测试，或者调用 joinChannel 进行通话。
• 直播场景下，该方法仅能由用户角色为主播的用户调用。如果用户由通信场景切换到直播场景，请务必调用 setClientRole 方法将用户角色设置为主播后再调用该方法。

返回

• 0：方法调用成功
• < 0：方法调用失败
  • ERR_REFUSED(-5)：无法启动测试，可能没有成功初始化

开始语音通话回路测试。

自从

v2.4.0。

该方法启动语音通话测试，目的是测试系统的音频设备（耳麦、扬声器等）和网络连接是否正常。在测试过程中，用户先说一段话，声音会在设置的时间间隔（单位为秒）后回放出来。如果用户能正常听到自己刚才说的话，就表示系统音频设备和网络连接都是正常的。

注解

• 请在加入频道前调用该方法。
• 调用 startEchoTest 后必须调用 stopEchoTest 以结束测试，否则不能进行下一次回声测试，也无法调用 joinChannel 加入频道。
• 直播场景下，该方法仅能由用户角色为主播的用户调用。

参数

intervalInSeconds

设置返回语音通话回路测试结果的时间间隔，取值范围为 [2, 10]，单位为秒，默认为 10 秒。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

停止语音通话回路测试。

返回

• 0： 方法调用成功
• <0： 方法调用失败
  • ERR_REFUSED(-5)：无法启动测试，可能没有成功初始化

启用网络测试。

该方法启用网络连接质量测试，用于检测用户网络接入质量。默认该功能为关闭状态。该方法主要用于以下两种场景：

• 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
• 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。

无论哪种场景，启用该方法会消耗一定的网络流量，影响通话质量。在收到 onLastmileQuality 回调后须调用 disableLastmileTest 停止测试，再加入频道或切换用户角色。

注解

• 该方法请勿与 startLastmileProbeTest 同时使用。
• 调用该方法后，在收到 onLastmileQuality 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此回调无法执行。
• 直播场景下，主播在加入频道后，请勿调用该方法。
• 加入频道前调用该方法检测网络质量后，SDK 会占用一路视频的带宽，码率与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后，无论是否调用了 disableLastmileTest，SDK 均会自动停止带宽占用。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

关闭网络测试。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

开始通话前网络质量探测，向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。

自从

v2.4.0。

启用该方法后，SDK 会依次返回如下 2 个回调：

• onLastmileQuality：视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。
• onLastmileProbeResult：视网络情况约 30 秒内返回。该回调通过客观数据反馈上下行网络质量，因此更客观。

该方法主要用于以下两种场景：

• 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
• 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。

注解

• 该方法会消耗一定的网络流量，影响通话质量，因此我们建议不要同时使用该方法和 enableLastmileTest。
• 调用该方法后，在收到 onLastmileQuality 和 onLastmileProbeResult 回调之前请不用调用其他方法， 否则可能会由于 API 操作过于频繁导致此方法无法执行。
• 直播场景下，如果本地用户为主播，请勿在加入频道后调用该方法。

参数

config

Last-mile 网络探测配置，详细定义见 LastmileProbeConfig。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

停止通话前网络质量探测。

自从

v2.4.0。

返回

• 0: 方法调用成功。
• < 0: 方法调用失败。

设置自定义的视频源。

实时通信过程中，Agora SDK 会启动默认的视频输入设备，即内置的摄像头，采集视频。但是，如果你需要自定义视频输入设备，你可以先通过 IVideoSource 类自定义视频源，再调用该方法将自定义的视频源加入到 SDK 中。

该方法在加入频道前后都能调用。

参数

source

自定义的视频源。详细定义见 IVideoSource