C++ API Reference for All Platforms

初始化 SDK 服务。

请确保在调用其他 API 前先调用 createAgoraRtcEngine 和 initialize 创建并初始化 IRtcEngine。

参数

context

详见 RtcEngineContext 。

返回

• 0(ERR_OK): 方法调用成功。
• < 0: 方法调用失败。
  • -1(ERR_FAILED): 一般性的错误（未明确归类）。
  • -2(ERR_INVALID_ARGUMENT): 未提供 IRtcEngineEventHandler 指针。
  • -7(ERR_NOT_INITIALIZED): SDK 初始化失败。请检查 context 内容是否正确。
  • -22(ERR_RESOURCE_LIMITED): 资源申请失败。当 app 占用资源过多，或系统资源耗尽时，SDK 分配资源失败，会返回该错误
  • -101(ERR_INVALID_APP_ID): 不是有效的 App ID。

销毁 IRtcEngine 对象。

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

注解

如需在销毁后再次创建 IRtcEngine 对象，需要等待 release 方法执行结束后再创建实例。

参数

sync	true: 该方法为同步调用。需要等待 IRtcEngine 资源释放后才能执行其他操作，所以我们建议在子线程中调用该方法，避免主线程阻塞。此外，我们不建议在 SDK 的回调中调用 release，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。SDK 会自动检测这种死锁并转为异步调用，但是检测本身会消耗额外的时间。 false: 该方法为异步调用。不需要等待 IRtcEngine 资源释放后就能执行其他操作。使用异步调用时要注意，不要在该调用后立即卸载 SDK 动态库，否则可能会因为 SDK 的清理线程还没有退出而崩溃。

设置频道场景。

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

警告

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

参数

profile

频道使用场景: CHANNEL_PROFILE_TYPE

返回

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

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

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

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

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

注解

该方法仅适用于直播场景。

参数

role	直播场景里的用户角色: CLIENT_ROLE_TYPE

返回

• 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.2.0

直播场景下，SDK 会默认设置用户角色为观众，你可以调用 setClientRole 设置用户角色为主播。

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

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

注解

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

参数

role	直播场景中的用户角色，详见 CLIENT_ROLE_TYPE
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 尚未初始化。

加入频道。

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中，用户必须调用 leaveChannel 退出当前通话，才能进入下一个频道。 成功调用该方加入频道后，本地会触发 onJoinChannelSuccess 回调；通信场景下的用户和直播场景下的主播加入频道后，远端会触发 onUserJoined 回调。 在网络状况不理想的情况下，客户端可能会与声网的服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 onRejoinChannelSuccess 回调。

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

注解

频道内每个用户的用户 ID 必须是唯一的。如果将 uid 设为 0，系统将自动分配一个 uid。如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 uid 是不同的。

警告

请务必确保用于生成 Token 的 App ID 和 initialize 方法初始化引擎时用的是同一个 App ID，否则会造成旁路推流失败。

参数

token	在你服务器上生成的 Token。详见使用 Token 鉴权。
channelId	标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a~z； 26 个大写英文字母 A~Z； 10个数字 0~9； 空格； "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。
info	(非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串，或频道相关信息。该信息不会传递给频道内的其他用户。
uid	(非必选项) 用户 ID，32位无符号整数。建议设置范围：1到 232-1，并保证唯一性。如果不指定（即设为0），SDK 会自动分配一个，并在 onJoinChannelSuccess 回调方法中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。

返回

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

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

自从

v3.3.0

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

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

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

注解

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

参数

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

返回

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

快速切换直播频道。

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

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

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

注解

该方法仅适用于直播场景中，角色为观众的用户。

参数

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

返回

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

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

自从

v3.3.0

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

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

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

注解

• 该方法仅适用于直播场景中，角色为观众的用户。
• 该方法和 switchChannel [1/2] 的区别在于， 该方法加了 options 参数，用于配置终端用户在切换到新的频道时是否自动订阅频道内所有远端音视频流。

参数

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

返回

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

离开频道。

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

当调用 joinChannel 方法后，必须调用 leaveChannel 结束通话，否则无法开始下一次通话。 不管当前是否在通话中，都可以调用 leaveChannel，没有副作用。该方法会把会话相关的所有资源释放掉。 该方法是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，SDK 会触发 onLeaveChannel 回调。 成功调用该方法离开频道后，本地会触发 onLeaveChannel 回调；通信场景下的用户和直播场景下的主播离开频道后，远端会触发 onUserOffline 回调。

注解

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

返回

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

设置发流端音画同步。

自从

v3.6.0

同一用户可能使用两个设备分别发送音频流和视频流，为保证接收端听到和看到的音频和视频的时间同步性，你可以在视频发送端调用该方法，并传入音频发送端的频道名、用户 ID。 SDK 会以发送的音频流的时间戳为基准进行自动调节发送的视频流，以保证即使在两个发送端的上行网络情况不一致（如分别使用 Wi-Fi 和 4G 网络）的情况下，也能让接收到的音视频具有时间同步性。

注解

声网推荐你在加入频道前调用该方法。

参数

channelId	标识音频发送端所在频道的频道名。
uid	音频发送端的用户 ID。

返回

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

更新 Token。

该方法用于更新 Token。如果启用了 Token 机制，过一段时间后使用的 Token 会失效。当：

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

App 应重新获取 Token，然后调用该方法更新 Token，否则 SDK 无法和服务器建立连接。

参数

token

新的 Token。

返回

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

获取设备管理员对象的指针。

参数

iid	想要获取的接口的接口。
inter	指向 DeviceManager 对象的指针。

返回

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

注册本地用户 User Account。

该方法为本地用户注册一个 User Account。注册成功后，该 User Account 即可标识该本地用户的身份，用户可以使用它加入频道。成功注册 User Account 后，本地会触发 onLocalUserRegistered 回调，告知本地用户的 UID 和 User Account。

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

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

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

注解

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

参数

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

返回

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

使用 User Account 加入频道。

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

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

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

注解

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

参数

token	在你服务器上生成的 Token。详见使用 Token 鉴权。
channelId	标识频道的频道名，最大不超过 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)
  • ERR_NOT_INITIALIZED (-7)
  • ERR_JOIN_CHANNEL_REJECTED(-17): 加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 IRtcEngine 频道， 当已经加入 IRtcEngine 频道的用户使用有效的频道名再次调用 IRtcEngine 类中的加入频道方法时，会返回此错误码。

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

自从

v3.3.0

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

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

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

注解

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

参数

token	在你服务器上生成的 Token。详见使用 Token 鉴权。
channelId	标识频道的频道名，最大不超过 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)
  • ERR_JOIN_CHANNEL_REJECTED(-17): 加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 IRtcEngine 频道， 当已经加入 IRtcEngine 频道的用户使用有效的频道名再次调用 IRtcEngine 类中的加入频道方法时，会返回此错误码。

通过 User Account 获取用户信息。

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

参数

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

返回

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

通过 UID 获取用户信息。

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

参数

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

返回

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

弃用:

开始语音通话回路测试。

该方法自 v2.4.0 起废弃。

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

注解

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

返回

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

开始语音通话回路测试。

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

注解

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

参数

intervalInSeconds

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

返回

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

开始音视频通话回路测试。

自从

v3.5.2

加入频道前，为测试用户本地发流、收流是否正常，你可以调用该方法进行音视频通话回路测试，即测试系统的音视频设备和用户的上下行网络是否正常。

开始测试后，用户需发出声音或面对摄像头，音频或视频会在约 2 秒后播放出来。如果音频播放正常，则表示系统音频设备和用户上下行网络均正常； 如果视频播放正常，则表示系统视频设备和用户上下行网络均正常。

注解

• 请在加入频道前调用该方法。
• 调用该方法后，必须调用 stopEchoTest 结束测试，否则该用户无法进行下一次音视频通话回路测试， 也无法加入频道。
• 直播场景下，该方法仅能由主播调用。

参数

config

音视频通话回路测试的配置。详见 EchoTestConfiguration。

返回

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

停止通话回路测试。

调用 startEchoTest [2/3] 或 startEchoTest [3/3] 后，如果你想停止通话回路测试，请调用本方法。

返回

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

设置声网云代理服务。

自从

v3.3.0

当用户的网络访问受到防火墙限制时，你需要将声网提供的 IP 和端口号添加到防火墙白名单，然后调用该方法开启云代理，并通过 proxyType 参数设置云代理类型。

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

自 v3.6.2 起，当用户调用该方法并成功加入频道后，SDK 会触发 onProxyConnected 回调，报告用户 ID、连接的代理类型和用户调用 joinChannel 到 SDK 触发该回调的经过的时间等。

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

注解

• 声网推荐你在频道外调用该方法。
• 对 3.3.x 版 SDK，使用 Force UDP 云代理时，旁路推流和跨频道媒体流转发功能不可用。对 3.4.0 及之后版 SDK，如果用户处于内网防火墙环境下，使用 Force UDP 云代理时，旁路推流和跨频道媒体流转发功能不可用。
• 使用 Force UDP 云代理时：
  • 调用 startAudioMixing 方法时无法播放 HTTP 协议的在线音频文件。
  • 旁路推流和跨频道媒体流转发功能会用 TCP 协议的云代理。

参数

proxyType

云代理类型，详见 CLOUD_PROXY_TYPE 。该参数为必填参数，如果你不赋值，SDK 会报错。

返回

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

启用视频模块。

该方法可以在加入频道前或者通话中调用，在加入频道前调用则自动开启视频模块；在通话中调用则由音频模式切换为视频模式。 调用 disableVideo 方法可关闭视频模式。 成功调用该方法后，远端会触发 onUserEnableVideo (true) 回调。

注解

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

返回

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

关闭视频模块。

该方法可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启纯音频模式，在通话中调用则由视频模式切换为纯音频模式。 调用 enableVideo 方法可开启视频模式。 成功调用该方法后，远端会触发 onUserEnableVideo (false) 回调

注解

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

返回

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

弃用:

设置视频编码配置。

该方法自 v2.3 起废弃。请改用 setVideoEncoderConfiguration 方法。

该方法设置视频编码属性（Profile）。每个属性对应一套视频参数，如分辨率、帧率、码率等。 当设备的摄像头不支持指定的分辨率时，SDK 会自动选择一个合适的摄像头分辨率，但是编码分辨率仍然用 setVideoProfile 指定的。

注解

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

参数

profile	视频属性。详见: VIDEO_PROFILE_TYPE 。
swapWidthAndHeight	SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高： true: 交换宽和高 false: 不交换宽和高（默认）

你可以直接通过视频属性 (profile) 来定义输出的视频是 Landscape（横屏）还是 Portrait（竖屏）模式，因此 声网建议你将参数设置为默认值。

返回

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

设置视频编码属性。

设置本地视频的编码属性。

注解

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

参数

config

视频编码参数配置。详见: VideoEncoderConfiguration 。

返回

• 0: 方法调用成功
• < 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 之前。

参数

config

摄像头采集配置，详见 CameraCapturerConfiguration 。

返回

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

初始化本地视图。

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

在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。退出频道后，绑定仍然有效，如果需要解除绑定，可以指定空(NULL)View 调用 setupLocalVideo。

注解

• 该方法在加入频道前后都能调用。
• 如果你希望在通话中更新本地用户视图的渲染或镜像模式，请使用 setLocalRenderMode 方法。

参数

canvas

视频画布信息: VideoCanvas 。

返回

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

初始化远端用户视图。

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

调用该接口时需要指定远端视频的 uid，一般可以在进频道前提前设置好。

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

注解

如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 setRemoteRenderMode 方法。

参数

canvas

视频画布信息: VideoCanvas 。

返回

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

开启视频预览。

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

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

启用了本地视频预览后，如果调用 leaveChannel 退出频道，本地预览依然处于启动状态，如需要关闭本地预览，需要调用 stopPreview。

返回

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

设置远端用户流的优先级。

设置远端用户的优先级。如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。 弱网下 SDK 会优先保证高优先级用户收到的流的质量。

注解

• 目前 SDK 仅允许将一名远端用户设为高优先级。
• 该方法需要在加入频道前调用。

参数

uid	远端用户的 ID。
userPriority	远端用户的需求优先级。详见: PRIORITY_TYPE 。

返回

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

停止本地视频预览。

调用 startPreview 后，如果你想关闭本地视频预览，请调用 stopPreview。

注解

请在加入频道前或离开频道后调用该方法。

返回

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

启用音频模块。

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

注解

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

返回

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

开关本地音频采集。

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

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

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

注解

• 该方法与 muteLocalAudioStream 的区别在于：
  • enableLocalAudio: 开启或关闭本地语音采集及处理。使用 enableLocalAudio 关闭或开启本地采集后，本地听远端播放会有短暂中断。
  • muteLocalAudioStream: 停止或继续发送本地音频流。
• 该方法在加入频道前后均可调用。在加入频道前调用只能设置设备状态，在加入频道后才会立即生效。

参数

enabled

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

返回

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

关闭音频模块。

注解

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

返回

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

设置音频编码属性。

注解

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

参数

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

返回

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

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

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

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

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

注解

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

参数

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

返回

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

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

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

注解

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

参数

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

返回

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

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

弃用:

该方法自 v3.3.0 起废弃。

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

注解

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

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

参数

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

返回

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

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

自从

v3.0.0

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

注解

• 请在加入频道后，调用该方法。
• 该方法调节的是本地播放的指定远端用户混音后的音量。

参数

uid	远端用户 ID。
volume	播放音量，取值范围为 [0,100]，其中： 0: 静音 100:（默认）原始音量

返回

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

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

注解

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

参数

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

返回

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

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

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

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

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

注解

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

参数

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

返回

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

开关本地视频采集。

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

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

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

注解

• 该方法在加入频道前后都能调用。
• 该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效。

参数

enabled

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

返回

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

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

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

注解

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

参数

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

返回

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

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

弃用:

该方法自 v3.3.0 起废弃。

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

注解

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

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

参数

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

返回

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

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

注解

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

参数

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

返回

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

设置订阅的视频流类型。

在网络条件受限的情况下，如果发送端没有调用 enableDualStreamMode (false) 关闭双流模式，接收端可以选择接收大流还是小流。其中，大流可以接为高分辨率高码率的视频流， 小流则是低分辨率低码率的视频流。

正常情况下，用户默认接收大流。如需接收小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。

视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 onApiCallExecuted 中返回。

注解

该方法在加入频道前后都能调用。如果既调用了 setRemoteVideoStreamType，也调用了 setRemoteDefaultVideoStreamType，则 SDK 以 setRemoteVideoStreamType 中的设置为准。

参数

userId	用户 ID。
streamType	视频流类型: REMOTE_VIDEO_STREAM_TYPE 。

返回

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

设置默认订阅的视频流类型。

在网络条件受限的情况下，如果发送端没有调用 enableDualStreamMode (false) 关闭双流模式， 接收端可以选择接收大流还是小流。其中，大流可以接为高分辨率高码率的视频流， 小流则是低分辨率低码率的视频流。

正常情况下，用户默认接收大流。如需默认接收所有用户的视频小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。视频小流默认 的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 onApiCallExecuted 中返回。

注解

• 该方法只能在加入频道前调用。声网不支持你在加入频道后修改默认订阅的视频流类型。
• 如果你既调用了该方法，也调用了 setRemoteVideoStreamType，则 SDK 以 setRemoteVideoStreamType 中的设置为准。

参数

streamType

视频流类型: REMOTE_VIDEO_STREAM_TYPE 。

返回

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

开启或关闭 Wi-Fi 加速功能。

自从

v3.6.2

当 SDK 发现集成加速插件的 Wi-Fi 路由器后，该功能才会生效，使路由器合理分配 Wi-Fi 频谱资源，以降低丢包率和时延，从而减少音视频卡顿。

当路由器提供加速服务后，SDK 会周期性触发 onWlAccStats 回调，报告 Wi-Fi 连接优化数据，并在 Wi-Fi 连接质量不佳时触发 onWlAccMessage 回调，报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

注解

• Wi-Fi 加速功能默认开启，但必须与集成加速插件的路由器配合使用才能生效，详见哪些 Wi-Fi 路由器可支持加速功能。如果 Wi-Fi 路由器不支持加速功能，系统性能不会受损。
• 加速功能生效后，路由器的 app 会显示加速效果和被加速 app 的名称。如果你不想在路由器的 app 中展示被加速 app 的名称，请调用 enableWirelessAccelerate(false) 关闭加速功能。
• 请在加入频道前或离开频道后调用该方法。
• 声网提供的 Wi-Fi 加速功能除应用于音视频流，还可以应用于其他第三方业务流，如私有信令、课件、RTMP 协议等。如有需要，请联系 sales@agora.io。

参数

enabled

设置是否开启 Wi-Fi 加速功能： true: 开启。 false: 关闭。

返回

• 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: 方法调用失败

开启本地语音音调回调。

自从

v3.7.0

该方法允许 SDK 定期向 app 报告本地用户的语音音调。开启本地音频采集并调用该方法后，SDK 会按设置的时间间隔触发 onLocalVoicePitchInHz 回调。

注解

该方法在加入频道前后均可调用。

参数

interval

设置 SDK 触发 onLocalVoicePitchInHz 回调的时间间隔： ≤ 0: 关闭 onLocalVoicePitchInHz 回调。 > 0: SDK 触发 onLocalVoicePitchInHz 回调的时间间隔，单位为毫秒。取值需大于等于 10 毫秒，如果小于 10 毫秒，SDK 会自动调整为 10 毫秒。

返回

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

开始客户端录音。

弃用:

该方法从 v2.9.1 起废弃，其默认录音采样率为 32 kHz，不可修改。请改用 startAudioRecording [3/3] 方法。

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

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

请确保 App 里指定的目录存在且可写。该接口需在 joinChannel 之后调用。如果调用 leaveChannel 时还在录音，录音会自动停止。

参数

filePath	录音文件的本地保存路径，由用户自行指定，需精确到文件名及格式，例如：/dir1/dir2/dir3/audio.aac。
quality	AUDIO_RECORDING_QUALITY_TYPE 。

返回

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

开始客户端录音。

弃用:

自 v3.4.0 废弃。请改用 startAudioRecording [3/3] 方法。

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

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

注解

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

参数

filePath	录音文件在本地保存的绝对路径，由用户自行指定，需精确到文件名及格式，例如：c:/music/audio.aac。
sampleRate	录音采样率（Hz），可以设为以下值： 16000 32000（默认） 44100 48000
quality	录音音质。详见 AUDIO_RECORDING_QUALITY_TYPE 。

返回

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

开始客户端录音。

自从

v3.4.0

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

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

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

注解

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

参数

config

录音配置。详见 AudioRecordingConfiguration。

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • -160(ERR_ALREADY_IN_RECORDING): 客户端正在录音。如需开始新的录音， 请先调用 stopAudioRecording 停止当前录音， 再调用 startAudioRecording

停止客户端录音。

返回

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

开始播放音乐文件。

弃用:

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

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

注解

• 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 WARN_AUDIO_MIXING_OPEN_ERROR = 701。
• 为避免阻塞，自 v3.4.5 起，该方法由同步调用改为异步调用。
• 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。
• Android 平台上，如果要播放 URL 地址以 http 开头的在线文件，你需要在 /app/Manifests/AndroidManifest.xml 文件中添加 android:usesCleartextTraffic="true"。

参数

filePath	音乐文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：C:\music\audio.mp4。 在 Android 上访问本地文件时，声网推荐填入 URI 地址或以 /assets/ 开头的路径。
loopback	true: 只有本地用户可以听到混音的音频； false: 本地用户和远端用户都能听到混音的音频。
replace	true: 只推送指定的本地音频文件或者线上音频文件，不传输麦克风收录的音频。 false: 本地音频文件与来自麦克风的音频流混音。
cycle	循环播放次数： 正整数: 循环播放的次数； -1: 无限循环。

返回

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

开始播放音乐文件。

自从

v3.4.0

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

注解

• 如需多次调用 startAudioMixing，请确保调用间隔大于 500 ms。
• 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，则 SDK 会报告 WARN_AUDIO_MIXING_OPEN_ERROR (701)。
• 在 Android 平台上调用该方法时，请注意如下：
  • 如需调用该方法，请确保使用 Android 4.2 或以上设备，且 API Level 不低于 16。
  • 如果播放的是在线音乐文件，声网建议不要使用重定向地址。重定向地址在某些机型上可能无法打开。
  • 如果在模拟器上调用该方法，则请确保音乐文件在 /sdcard/ 目录下，且格式为 MP3。
  • 如果要播放 URL 地址以 http 开头的在线文件，你需要在 /app/Manifests/AndroidManifest.xml 文件中添加 android:usesCleartextTraffic="true"。
  • 为避免阻塞，自 v3.4.5 起，该方法由同步调用改为异步调用。
• 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。

参数

filePath	音乐文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：C:\music\audio.mp4。 在 Android 上访问本地文件时，声网推荐填入 URI 地址或以 /assets/ 开头的路径。
loopback	是否只在本地播放音乐文件： true: 只在本地播放音乐文件，只有本地用户能听到音乐。 false: 将本地播放的音乐文件发布至远端，本地用户和远端用户都能听到音乐。
replace	是否用音乐文件替换麦克风采集的音频： true: 替换。用户只能听到音乐。 false: 不替换。用户可以听到音乐和麦克风采集的音频。
cycle	音乐文件的播放次数。 ≥ 0: 播放次数。例如，0 表示不播放；1 表示播放 1 次。 -1: 无限循环播放。
startPos	音乐文件的播放位置，单位为毫秒。

返回

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

设置当前音乐文件的播放速度。

自从

v3.5.1

注解

你需要在调用 startAudioMixing [2/2] 并 收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

参数

speed

播放速度。推荐取值范围为 [50,400]，其中： 50: 0.5 倍速。 100: 原始速度。 400: 4 倍速。

返回

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

停止播放音乐文件。

该方法停止播放音乐文件。请在频道内调用该方法。

返回

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

暂停播放音乐文件。

该方法暂停播放音乐文件。请在频道内调用该方法。

返回

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

指定当前音乐文件的播放音轨。

自从

v3.5.1

获取音乐文件的音轨数量后，你可以调用该方法指定任一音轨进行播放。例如，如果一个多音轨文件的 不同音轨存放了不同语言的歌曲，则你可以调用该方法设置音乐文件的播放语言。

注解

• 你需要在调用 startAudioMixing [2/2] 并 收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
• 该方法仅适用于 Android、iOS 和 Windows。
• 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。

参数

index

指定的播放音轨。取值范围为 [0, getAudioTrackCount()).

返回

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

获取当前音乐文件的音轨数量。

自从

v3.5.1

注解

• 你需要在调用 startAudioMixing [2/2] 并 收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
• 该方法仅适用于 Android、iOS 和 Windows。
• 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。

返回

• > 0: 方法调用成功，返回当前音乐文件的音轨数量。
• < 0: 方法调用失败。

设置当前音乐文件的声道模式。

自从

v3.5.1

在双声道音乐文件中，左声道和右声道可以存储不同的音频数据。根据实际需要，你可以设置声道模式为原始模式、 左声道模式、右声道模式或混合模式。例如，在 KTV 场景中，音乐文件的左声道存储了伴奏，右声道存储了原唱的歌声。 如果你只需听伴奏，调用该方法设置音乐文件的声道模式为左声道模式；如果你需要同时听伴奏和原唱，调用该方法设置声 道模式为混合模式。

注解

• 你需要在调用 startAudioMixing [2/2] 并 收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
• 该方法仅适用于双声道的音乐文件。

参数

mode	声道模式。详见 AUDIO_MIXING_DUAL_MONO_MODE。

返回

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

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

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

返回

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

弃用:

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

设置音频高音质选项。

参数

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

返回

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

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

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

注解

• 你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
• 调用该方法不影响调用 playEffect 播放音效文件的音量。

参数

volume

音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。

返回

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

调节音乐文件本端播放音量。

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

注解

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

参数

volume

音乐文件音量范围为 0~100。100 （默认值） 为原始文件音量。

返回

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

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

该方法获取混音的音乐文件本地播放音量，方便排查音量相关问题。

注解

• 请在频道内调用该方法。
• 你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

返回

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

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

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

注解

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

参数

volume

音乐文件音量范围为 0~100。100 （默认值） 为原始文件音量。

返回

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

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

该接口可以方便开发者排查音量相关问题。

注解

• 请在频道中调用该方法。
• 你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

返回

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

获取音乐文件总时长。

弃用:

自 v3.5.1 废弃，请改用 getAudioFileInfo

该方法获取音乐文件总时长，单位为毫秒。请在频道内调用该方法。

注解

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

返回

• ≥ 0: 方法调用成功返回音乐文件时长。
• < 0: 方法调用失败

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

该方法获取当前音乐文件播放进度，单位为毫秒。请在频道内调用该方法。

注解

• 你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
• 如需多次调用 getAudioMixingCurrentPosition，请确保调用间隔大于 500 ms。

返回

• ≥ 0: 方法调用成功，返回当前音乐文件播放进度（ms）。0 表示当前音乐文件未开始播放。
• < 0: 方法调用失败

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

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

注解

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

参数

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

返回

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

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

自从

v3.0.1

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

注解

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

参数

pitch

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

返回

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

获取音效文件的播放音量。

音量范围为 0~100。100 （默认值）为原始文件音量。

注解

该方法需要在 playEffect 后调用。

返回

• 音效文件的音量。
• < 0: 方法调用失败

设置音效文件的播放音量。

音量范围为 0~100。100 （默认值）为原始文件音量。

注解

该方法需要在 playEffect 后调用。

参数

volume

该方法设置音效的音量。

返回

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

实时调整音效文件的播放音量。

注解

该方法需要在 playEffect 后调用。

参数

soundId	指定音效的 ID。每个音效均有唯一的 ID。
volume	播放音量。音量范围为 0~100。100 （默认值）为原始文件音量。

返回

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

开启/关闭本地人脸检测。仅适用于 Android 和 iOS。

自从

v3.0.1

注解

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

开启本地人脸检测后，SDK 会触发 onFacePositionChanged 回调向你报告人脸检测的信息：

• 摄像头采集的画面大小
• 人脸在 View 中的位置
• 人脸距设备屏幕的距离

参数

enable

是否开启人脸检测： true：开启人脸检测 false：（默认）关闭人脸检测

返回

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

播放指定音效文件。

弃用:

自 v3.4.0 废弃， 请改用 playEffect [2/2] 方法。

你可以多次调用该方法，通过传入不同的音效文件的 soundID 和 filePath，同时播放多个音效文件，实现音效叠加。为获得最佳用户体验，我们建议同时播放的音效文件不要超过 3 个。在 macOS 和 Windows 上，该方法不支持同时播放多个在线音效文件。

注解

• 该方法需要在加入频道后调用。
• 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。
• Android 平台上，如果要播放 URL 地址以 http 开头的在线文件，你需要在 /app/Manifests/AndroidManifest.xml 文件中添加 android:usesCleartextTraffic="true"。
• 如果你需要通过 playEffect 播放在线音效文件，声网建议你将在线音效文件缓存到本地设备，调用 preloadEffect 将缓存的音效文件预加载到内存中，再调用 playEffect 播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。

参数

soundId	指定音效的 ID。每个音效均有唯一的 ID。如果你已通过 preloadEffect 将音效加载至内存，确保这里设置的 soundId 与 preloadEffect 设置的 soundId 相同。
filePath	音效文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：C:\music\audio.mp4。 在 Android 上访问本地文件时，声网推荐填入 URI 地址或以 /assets/ 开头的路径。
loopCount	设置音效循环播放的次数： 0: 播放音效一次； 1: 播放音效两次； -1: 无限循环播放音效，直至调用 stopEffect 或 stopAllEffects 后停止。
pitch	设置音效的音调 取值范围为 [0.5, 2]。默认值为 1.0，表示不需要修改音调。取值越小，则音调越低。
pan	设置是否改变音效的空间位置。取值范围为 [-1.0, 1.0]: 0.0: 音效出现在正前方； 1.0: 音效出现在右边； -1.0: 音效出现在左边。
gain	设置是否改变单个音效的音量。取值范围为 [0.0, 100.0]。默认值为 100.0。取值越小，则音效的音量越低。
publish	设置是否将音效传到远端： true: 音效在本地播放的同时，会发布到声网云端，因此远端用户也能听到该音效； false: 音效不会发布到声网云端，因此只能在本地听到该音效。

返回

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

播放指定的本地或在线音效文件。

自从

v3.4.0

你可以多次调用该方法，传入不同的 soundId 和 filePath，同时播放多个音效文件。 为获得最佳用户体验，声网推荐同时播放的音效文件不超过 3 个。

音效文件播放结束后，SDK 会触发 onAudioEffectFinished 回调。

注解

• 该方法需要在加入频道后调用。
• 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。
• Android 平台上，如果要播放 URL 地址以 http 开头的在线文件，你需要在 /app/Manifests/AndroidManifest.xml 文件中添加 android:usesCleartextTraffic="true"。
• 如果你需要通过 playEffect 播放在线音效文件，声网建议你将在线音效文件缓存到本地设备，调用 preloadEffect 将缓存的音效文件预加载到内存中，再调用 playEffect 播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。

参数

soundId	音效的 ID。每个音效的 ID 具有唯一性。 如果你已通过 preloadEffect 将音效加载至内存， 请确保该参数与 preloadEffect 中设置的 soundId 相同。
filePath	音效文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：C:\music\audio.mp4。 如果你已通过 preloadEffect 将音效加载至内存， 请确保该参数与 preloadEffect 中设置的 filePath 相同。 在 Android 上访问本地文件时，声网推荐填入 URI 地址或以 /assets/ 开头的路径。
loopCount	音效循环播放的次数。 ≥ 0: 循环播放次数。例如，1 表示循环播放 1 次，即总计播放 2 次。 -1: 无限循环播放。
pitch	音效的音调，取值范围为 [0.5,2.0]。默认值为 1.0，表示原始音调。取值越小，则音调越低。
pan	音效的空间位置。取值范围为 [-1.0,1.0]，例如： -1.0: 音效出现在左边 0.0: 音效出现在正前方 1.0: 音效出现在右边
gain	音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0，表示原始音量。取值越小，则音量越低。
publish	是否将音效发布至远端： true: 发布。本地用户和远端用户都能听到音效。 false: 不发布。只有本地用户能听到音效。
startPos	音效文件的播放位置，单位为毫秒。

返回

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

停止播放指定音效文件。

参数

soundId

指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回

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

停止播放所有音效文件。

返回

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

将音效文件加载至内存。

该方法将指定音效文件预加载至内存。

注解

• 该方法不支持在线音频文件。支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。
• 为保证通信畅通，请注意控制预加载音效文件的大小。
• 该方法在加入频道前后均可调用。

参数

soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。
filePath	音效文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：C:\music\audio.mp4。 在 Android 上访问本地文件时，声网推荐填入 URI 地址或以 /assets/ 开头的路径。

返回

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

从内存释放某个预加载的音效文件。

参数

soundId

指定音效文件的 ID。每个音效文件均有唯一的 ID

返回

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

暂停音效文件播放。

参数

soundId

指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回

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

暂停所有音效文件播放。

返回

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

恢复播放指定音效文件。

参数

soundId

指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回

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

恢复播放所有音效文件。

返回

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

获取指定音频文件信息。

自从

v3.4.0

成功调用该方法后，SDK 会触发 onRequestAudioFileInfo 回调， 报告指定音频文件的时长等信息。你可以多次调用该方法，获取多个音频文件的信息。

注解

• 该方法需要在加入频道后调用。
• 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。
• 自 v3.7.0 起，getEffectDuration 的行为从“获取指定音效文件总时长”变更为“获取音频文件信息”。

参数

filePath

文件路径： Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：C: \music\audio.mp4。 Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note: 通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如：content://com.android.providers.media.documents/document/audio%3A14441。 iOS 和 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。

返回

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

设置指定音效文件的播放位置。

自从

v3.4.0

成功设置后，本地音效文件会在指定位置开始播放。

注解

该方法需要在 playEffect 后调用。

参数

soundId	音效 ID。请确保与 playEffect 中设置的 soundId 一致。
pos	音效文件的播放位置，单位为毫秒。

返回

• 0: 方法调用成功
• < 0: 方法调用失败
  • -22(ERR_RESOURCE_LIMITED): 无法找到音效文件。请填写正确的 soundId

获取指定音效文件的播放进度

自从

v3.4.0

注解

该方法需要在 playEffect 后调用。

参数

soundId

音效 ID。请确保与 playEffect 中设置的 soundId 一致。

返回

• ≥ 0: 方法调用成功
• < 0: 方法调用失败
  • -22(ERR_RESOURCE_LIMITED): 无法找到音效文件。请填写正确的 soundId

获取指定音频文件信息。

自从

v3.5.1

成功调用该方法后，SDK 会触发 onRequestAudioFileInfo 回调， 报告指定音频文件的时长等信息。你可以多次调用该方法，获取多个音频文件的信息。

注解

• 该方法需要在加入频道后调用。
• 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。

参数

filePath

文件路径： Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：C: \music\audio.mp4。 Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note: 通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如：content://com.android.providers.media.documents/document/audio%3A14441。 iOS 和 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。

返回

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

开启或关闭 AI 降噪模式。

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

1. 确保已集成如下动态库：
   • Android: libagora_ai_denoise_extension.so
   • iOS/macOS: AgoraAIDenoiseExtension.xcframework
   • Windows: libagora_ai_denoise_extension.dll
2. 调用 enableDeepLearningDenoise(true)。

AI 降噪模式对设备性能有要求。只有在设备性能良好的情况下，SDK 才会成功开启 AI 降噪模式。例如， 支持在如下设备及其之后的型号中开启 AI 降噪模式：

• iPhone 6S
• MacBook Pro 2015
• iPad Pro 第二代
• iPad mini 第五代
• iPad Air 第三代

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

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

注解

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

参数

enable

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

返回

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

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

如果想调用 setRemoteVoicePosition 实现听声辨位的功能，请确保在加入频道前调用该方法开启远端用户的语音立体声。

参数

enabled

是否开启远端用户语音立体声： true: 开启 false: 关闭

返回

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

设置远端用户的语音位置。

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

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

注解

• 为获得最佳听觉体验，我们建议用户佩戴有线耳机。
• 该方法需要在加入频道后调用。

参数

uid	远端用户的 ID
pan	设置远端用户声音的空间位置，取值范围为 [-1.0,1.0]: (默认）0.0: 声音出现在正前方。 -1.0: 声音出现在左边。 1.0: 声音出现在右边。
gain	设置远端用户声音的音量，取值范围为 [0.0,100.0]，默认值为 100.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。详见 AUDIO_EQUALIZATION_BAND_FREQUENCY 。
bandGain	每个 band 的增益，单位是 dB，每一个值的范围是 [-15,15]。

返回

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

设置本地音效混响。

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

注解

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

参数

reverbKey	混响音效 Key。该方法共有 5 个混响音效 Key: AUDIO_REVERB_TYPE 。
value	各混响音效 Key 所对应的值。详见 AUDIO_REVERB_TYPE

返回

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

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

弃用:

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

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

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

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

注解

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

参数

voiceChanger

预设本地语音变声、美音或语聊美声效果选项，默认值为 VOICE_CHANGER_OFF，即原声。详见 VOICE_CHANGER_PRESET 。

返回

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

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

弃用:

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

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

注解

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

参数

reverbPreset

本地语音混响选项，默认值为 AUDIO_REVERB_OFF，即原声。详见 AUDIO_REVERB_PRESET 。 为达到更好的混响效果，声网推荐使用以 AUDIO_REVERB_FX 为前缀的枚举值。

返回

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

设置 SDK 预设的美声效果。

自从

v3.2.0

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

为获取更好的人声效果，声网推荐你在调用该方法前将 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) 或 AUDIO_PROFILE_IOT(6)，否则该方法不生效。
• 该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
• 调用该方法后，声网不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  • setAudioEffectPreset
  • setVoiceBeautifierPreset
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset

参数

preset

预设的美声效果选项，详见 VOICE_BEAUTIFIER_PRESET

返回

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

设置 SDK 预设的人声音效。

自从

v3.2.0

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

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

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

注解

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

参数

preset

预设的音效选项，详见 AUDIO_EFFECT_PRESET

返回

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

设置 SDK 预设的变声效果。

自从

v3.3.1

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

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

注解

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

参数

preset

预设的变声效果选项: VOICE_CONVERSION_PRESET

返回

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

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

自从

v3.2.0

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

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

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

注解

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