Agora C++ API Reference for All Platforms

初始化 Agora SDK 服务。

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

参数

context

详见 RtcEngineContext 。

返回

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

销毁 IRtcEngine 对象。

参数

sync	true: 同步调用。在等待 IRtcEngine 对象资源释放后再返回。App 不应该在 SDK 产生的回调中调用该接口，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。SDK 会自动检测这种死锁并转为异步调用，但是检测本身会消耗额外的时间。 false: 异步调用。不等 IRtcEngine 对象资源释放就立即返回。SDK 会自行释放所有资源。使用异步调用时要注意，不要在该调用后立即卸载 SDK 动态库，否则可能会因为 SDK 的清理线程还没有退出而崩溃。

设置直播场景下的频道模式。

该方法用于设置频道模式（Profile）。Agora RtcEngine 需知道 App 的使用场景（例如通信模式或直播模式）, 从而使用不同的优化手段。

注解

• 该方法仅适用于直播模式。
• 相同频道内的所有用户必须使用相同的频道模式。
• 如果想要切换模式，则需要先调用 release 销毁当前引擎，然后重新调用 createAgoraRtcEngine 创建新的对象，并在调用 initialize 方法后再调用该方法切换频道模式。
• 该方法必须在 joinChannel 前调用和进行设置，进入频道后无法再设置。
• 在通信模式下，Agora SDK 不支持 texture 编码，只支持原始音视频数据。

参数

profile

频道属性: CHANNEL_PROFILE_TYPE 。

返回

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

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

在加入频道前，用户需要通过本方法设置观众（默认）或主播模式。在加入频道后，用户可以通过本方法切换用户模式。 直播模式下，如果你在加入频道后调用该方法切换用户角色，调用成功后，本地会触发 onClientRoleChanged 回调；远端会触发 onUserJoined 回调或 onUserOffline (BECOME_AUDIENCE) 回调。

参数

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

注解

该方法仅适用于直播模式。

返回

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

加入频道。

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

注解

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

警告

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

参数

token	动态秘钥。 安全要求不高: 将值设为 NULL。 安全要求高: 将值设置为 Token。如果你已经启用了 App Certificate, 请务必使用 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: 方法调用成功；
• < 0: 方法调用失败。
  • ERR_INVALID_ARGUMENT (-2)
  • ERR_NOT_READY (-3)
  • ERR_REFUSED (-5)

快速切换直播频道。

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

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

注解

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

参数

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

返回

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

离开频道。

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

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

注解

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

返回

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

更新 Token。

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

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

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

参数

token

新的 Token。

返回

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

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

参数

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。如果有用户通过 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 加入频道。

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

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

注解

为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Agora Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

参数

token	在 App 服务器端生成的用于鉴权的 Token： 安全要求不高：你可以使用控制台生成的临时 Token，详见 获取临时 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: 方法调用失败

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

DEPRECATED 开始语音通话回路测试。

该方法自 v2.4.0 起废弃。

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

注解

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

返回

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

开始语音通话回路测试。

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

注解

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

参数

intervalInSeconds

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

返回

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

停止语音通话回路测试。

返回

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

启用视频模块。

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

注解

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

返回

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

关闭视频模块。

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

注解

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

返回

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

DEPRECATED 设置视频编码配置。

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

该方法设置视频编码属性（Profile）。每个属性对应一套视频参数，如分辨率、帧率、码率等。 当设备的摄像头不支持指定的分辨率时，Agora 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。

注解

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

参数

config

摄像头采集偏好，详见 CameraCapturerConfiguration 。

返回

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

设置本地视图。

该方法设置本地视频显示信息。 App 通过调用此接口绑定本地视频流的显示视窗(view)，并设置视频显示模式。 在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。退出频道后，绑定仍然有效，如果需要解除绑定，可以指定空(NULL)View 调用 setupLocalVideo。

参数

canvas

视频画布信息: VideoCanvas 。

返回

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

设置远端用户视图。

该方法绑定远端用户和显示视图，即设定 uid 指定的用户用哪个视图显示。调用该接口时需要指定远端视频的 uid，一般可以在进频道前提前设置好。

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

参数

canvas

视频画布信息: VideoCanvas 。

返回

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

开启视频预览。

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

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

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

返回

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

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

设置远端用户的优先级。如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。 该方法可以与 setRemoteSubscribeFallbackOption 搭配使用。如果开启了订阅流回退选项，弱网下 SDK 会优先保证高优先级用户收到的流的质量。

注解

目前 Agora SDK 仅允许将一名远端用户设为高优先级。

参数

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

返回

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

停止视频预览。

返回

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

启用音频模块。

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

注解

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

返回

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

开关本地音频采集。

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

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

语音功能关闭或重新开启后，会收到回调 onMicrophoneEnabled。

注解

• 该方法需要在 joinChannel 之后调用才能生效。
• 该方法与 muteLocalAudioStream 的区别在于：
  • enableLocalAudio: 开启或关闭本地语音采集及处理。使用 enableLocalAudio 关闭或开启本地采集后，本地听远端播放会有短暂中断。
  • muteLocalAudioStream: 停止或继续发送本地音频流。
• 调用 enableLocalAudio(false) 关闭本地采集后，系统会走媒体音量；调用 enableLocalAudio(true) 重新打开本地采集后，系统会恢复为通话音量。

参数

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

开关本地音频发送。

该方法用于允许/禁止往网络发送本地音频流。 成功调用该方法后，远端会触发 onUserMuteAudio 回调。

注解

• 该方法不影响录音状态，因为并没有禁用录音设备。
• 如果你在该方法后调用 setChannelProfile 方法，SDK 会根据你设置的频道模式以及用户角色，重新设置是否停止发送本地音频。因此我们建议在 setChannelProfile 后调用该方法。

参数

mute	true: 停止发送本地音频流； false: 继续发送本地音频流（默认）。

返回

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

接收／停止接收所有音频流。

参数

mute	true: 停止接收所有音频流； false: 继续接收所有音频流（默认）。

返回

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

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

参数

mute	true: 默认停止接收所有音频流； false: 默认接收所有音频流（默认）。

返回

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

接收／停止接收指定音频流。

注解

如果之前有调用过 muteAllRemoteAudioStreams (true) 停止订阅所有远端音频，在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams (false)。 muteAllRemoteAudioStreams 是全局控制，muteRemoteAudioStream 是精细控制。

参数

userId	指定用户的 ID
mute	true: 停止接收指定音频流； false: 继续接收指定音频流（默认）。

返回

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

开关本地视频发送。

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

注解

• 调用该方法时，SDK 不再发送本地视频流，但摄像头仍然处于工作状态。相比于 enableLocalVideo (false) 用于控制本地视频流发送的方法，该方法响应速度更快。该方法不影响本地视频流获取，没有禁用摄像头。
• 如果你在该方法后调用 setChannelProfile 方法，SDK 会根据你设置的频道模式以及用户角色，重新设置是否停止发送本地视频。因此我们建议在 setChannelProfile 后调用该方法。

参数

mute	true: 不发送本地视频流 false: 发送本地视频流（默认）。

返回

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

开关本地视频采集。

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

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

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

注解

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

参数

enabled

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

返回

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

接收／停止接收所有远端视频流。

参数

mute	true: 停止接收所有远端视频流； false: 允许接收所有远端视频流（默认）。

返回

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

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

参数

mute	true: 默认停止接收所有远端视频； false: 默认接收所有远端视频（默认）。

返回

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

接收／停止接收指定远端用户的视频流。

注解

如果之前调用过 muteAllRemoteVideoStreams (true) 停止接收放所有远端视频流，在调用本 API 之前请确保你已调用 muteAllRemoteVideoStreams (false) 。muteAllRemoteVideoStreams 是全局控制，muteRemoteVideoStream 是精细控制。

参数

userId	指定用户的用户 ID。
mute	true: 停止接收指定远端用户的视频流； false: 允许接收指定远端用户的视频流（默认）。

返回

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

设置订阅的视频流类型。

如果发送端选择发送视频双流 (大流，即高分辨率、高码率视频流，或小流，即低分辨率、低码率视频流)，接收端可以选择接收大流还是小流。该方法可以根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。

• 如果发送端用户已调用 enableDualStreamMode 启用了双流模式，默认接收大流。如需使用小流，可调用本方法进行切换；
• 如果发送端用户未启用双流模式，默认接收大流。

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

参数

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

返回

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

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

如果发送端选择发送视频双流 (大流，即高分辨率、高码率视频流，或小流，即低分辨率、低码率视频流)，接收端可以选择接收大流还是小流。

• 如果用户已调用 enableDualStreamMode 启用了双流模式，默认接收大流。如需使用小流，可调用本方法进行切换。
• 如果用户未启用双流模式，默认接收大流。

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

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

参数

streamType

视频流类型: REMOTE_VIDEO_STREAM_TYPE 。

返回

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

启用说话者音量提示。

该方法允许 SDK 定期向 App 反馈当前谁在说话以及说话者的音量。启用该方法后，无论频道内是否有人说话，都会在 onAudioVolumeIndication 回调中按设置的间隔时间返回音量提示。

参数

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

返回

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

DEPRECATED 开始客户端录音。

该方法从 v2.9.1 起废弃，其默认录音采样率为 32 kHz，不可修改。请改用新的 startAudioRecording2 方法。

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

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

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

参数

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

返回

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

开始客户端录音。

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	录音采样率（kHz），可以设为以下值： 16 32（默认） 44.1 48
quality	录音音质。详见 AUDIO_RECORDING_QUALITY_TYPE 。

返回

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

停止客户端录音。

停止录音。该接口需要在 leaveChannel 之前调用，不然会在调用 leaveChannel 时自动停止。

返回

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

开始播放音乐文件。

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

注解

• 请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。
• 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 WARN_AUDIO_MIXING_OPEN_ERROR = 701。

参数

filePath	指定需要混音的本地或在线音频文件的绝对路径。支持的音频格式包括：3GP、ASF、ADTS、AVI、MP3、MPEG-4、SAMI 和 WAVE。详见： Supported Media Formats in Media Foundation 。
loopback	true: 只有本地用户可以听到混音的音频； false: 本地用户和远端用户都能听到混音的音频。
replace	true: 只推送指定的本地音频文件或者线上音频文件，不传输麦克风收录的音频。 false: 本地音频文件与来自麦克风的音频流混音。
cycle	循环播放次数： 正整数: 循环播放的次数； -1: 无限循环。

返回

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

停止播放音乐文件。

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

返回

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

暂停播放音乐文件。

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

返回

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

恢复播放音乐文件。

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

返回

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

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

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

注解

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

参数

volume

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

返回

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

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

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

参数

volume

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

返回

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

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

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

注解

请在频道内调用该方法。

返回

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

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

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

参数

volume

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

返回

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

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

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

注解

请在频道中调用该方法

返回

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

获取音乐文件总时长。

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

返回

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

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

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

返回

• ≥ 0: 方法调用成功返回音乐文件播放进度。
• < 0: 方法调用失败。

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

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

参数

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

返回

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

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

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

返回

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

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

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

参数

volume

该方法设置音效的音量。

返回

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

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

参数

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

返回

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

播放指定音效文件。

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

参数

soundId

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

注解

如果你已通过 preloadEffect 将音效加载至内存，确保这里设置的 soundId 与 preloadEffect 设置的 soundId 相同。

参数

filePath	音效文件的绝对路径或 URL 地址。
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: 音效在本地播放的同时，会发布到 Agora 云端，因此远端用户也能听到该音效； false: 音效不会发布到 Agora 云端，因此只能在本地听到该音效。

返回

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

停止播放指定音效文件。

参数

soundId

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

返回

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

停止播放所有音效文件。

返回

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

将音效文件加载至内存。

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

注解

该方法不支持在线音频文件。

为保证通信畅通，请注意控制预加载音效文件的大小，并在 joinChannel 前就使用该方法完成音效预加载。音频文件支持以下音频格式: mp3、aac、m4a、3gp，和 wav。

参数

soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。
filePath	音效文件的绝对路径。

返回

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

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

参数

soundId

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

返回

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

暂停音效文件播放。

参数

soundId

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

返回

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

暂停所有音效文件播放。

返回

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

恢复播放指定音效文件。

参数

soundId

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

返回

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

恢复播放所有音效文件。

返回

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

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

如果想调用 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: 方法调用失败。

设置本地音效混响。

参数

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

返回

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

设置本地语音变声。

注解

该方法不能与 setLocalVoiceReverbPreset 方法一同使用，否则先调的方法会不生效。

参数

voiceChanger

预设本地语音变声效果选项，详见 VOICE_CHANGER_PRESET 。

返回

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

设置本地语音混响。

设置预置的本地语音的混响效果选项。

注解

• 该方法不能与 setLocalVoiceReverb 同时调用。
• 该方法不能与 setLocalVoiceChanger 方法一同使用，否则先调的方法会不生效。

参数

reverbPreset

预设的本地语音混响效果选项，详见 AUDIO_REVERB_PRESET 。

返回

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

设置日志文件。

设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。 App 必须保证指定的目录存在而且可写。

注解

• Windows 平台下日志文件的默认地址为："C:\Users\<user_name>\AppData\Local\Agora\<process_name>"。
• 如需调用本方法，请在调用 initialize 方法初始化 IRtcEngine 对象后立即调用，否则可能造成输出日志不完整。

参数

filePath

日志文件的完整路径。该日志文件为 UTF-8 编码。

返回

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

设置日志输出等级。

设置 Agora SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。选择一个级别，你就可以看到在该级别之前所有级别的日志信息。

例如，你选择 WARNING 级别，就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。

参数

filter

设置过滤等级: LOG_FILTER_TYPE 。

返回

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

设置日志文件大小。

设置 SDK 输出的日志文件大小，单位为 KB。 Agora SDK 设有 2 个日志文件，每个文件大小为 512 KB。如果你将 fileSizeInKByte 设置为 1024 KB， SDK 会最多输出 2 M 的日志文件。如果日志文件超出设置值，新的日志会覆盖之前的日志。

参数

fileSizeInKBytes

指定 SDK 输出日志文件的内存大小，单位为 KB。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败, 有可能是因为传入的参数无效。

设置本地视图显示模式。

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

参数

renderMode

RENDER_MODE_TYPE 。

返回

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

设置远端视图显示模式。

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

参数

userId	远端用户 ID。
renderMode	RENDER_MODE_TYPE 。

返回

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

设置本地视频镜像模式。

该方法须在 startPreview 前设置。如果在开启预览后设置，需要重新开启预览才能生效。

注解

SDK 默认启用镜像模式。

参数

mirrorMode

VIDEO_MIRROR_MODE_TYPE 。

返回

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

开关双流模式。

该方法设置单流（默认）或者双流模式。发送端开启双流模式后，接收端可以选择接收大流还是小流。其中，大流指高分辨率、高码率的视频流，小流指低分辨率、低码率的视频流。

参数

enabled

true: 双流； false: 单流（默认）。

设置外部音频采集参数。请在 joinChannel 前调用该方法。

参数

enabled	true: 开启使用外部音频源的功能； false: 关闭使用外部音频源的功能（默认）。
sampleRate	外部音频源的采样率 (Hz)，可设置为 8000，16000，32000，44100 或 48000。
channels	外部音频源的通道数，可设置为 1 或 2: 1: 单声道 2: 双声道

返回

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

设置外部音频渲染。

该方法适用于需要自行渲染音频的场景。开启外部音频渲染后，你可以通过调用 pullAudioFrame 方法拉取远端音频数据。 App 可以对拉取到的原始音频数据进行处理后再渲染，获取想要的音频效果。

注解

开启外部音频渲染后，App 会无法从 onPlaybackAudioFrame 回调中获得数据。

参数

enabled	true: 开启外部音频渲染。 false: （默认）关闭外部音频渲染。
sampleRate	外部音频渲染的采样率 (Hz)，可设置为 8000，16000，32000，44100 或 48000。
channels	外部音频渲染的声道数，可设置为 1 或 2: 1: 单声道 2: 双声道

返回

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

设置录制的声音格式。

该方法设置 onRecordAudioFrame 回调的录制声音格式。

参数

sampleRate	指定 onRecordAudioFrame 中返回数据的采样率，可设置为 8000、 16000、 32000、 44100 或 48000。
channel	指定 onRecordAudioFrame 中返回数据的通道数，可设置为 1 或 2: 1: 单声道 2: 双声道
mode	onRecordAudioFrame 回调的使用模式: RAW_AUDIO_FRAME_OP_MODE_TYPE 。
samplesPerCall	指定 onRecordAudioFrame 中返回数据的采样点数，如 RTMP 推流应用中通常为 1024。samplesPerCall = (int)(sampleRate × sampleInterval)，其中：sampleInterval ≥ 0.01 单位为秒。

返回

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

设置播放的声音格式。

参数

sampleRate	指定 onPlaybackAudioFrame 中返回数据的采样率，可设置为 8000，16000，32000，44100 或 48000。
channel	指定 onPlaybackAudioFrame 中返回数据的通道数，可设置为 1 或 2: 1: 单声道 2: 双声道
mode	指定 onPlaybackAudioFrame 的使用模式: RAW_AUDIO_FRAME_OP_MODE_TYPE 。
samplesPerCall	指定 onPlaybackAudioFrame 中返回数据的采样点数，如RTMP推流应用中通常为 1024。samplesPerCall = (int)(sampleRate × sampleInterval)，其中：sampleInterval ≥ 0.01 单位为秒。

返回

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

设置录制与播放声音混音后的数据格式

参数

sampleRate	指定 onMixedAudioFrame 中返回数据的采样率，可设置为 8000，16000，32000，44100 或 48000。
samplesPerCall	指定 onMixedAudioFrame 中返回数据的采样点数，如 RTMP 推流应用中通常为 1024。samplesPerCall = (int)(sampleRate × sampleInterval)，其中：sampleInterval ≥ 0.01 单位为秒。

返回

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

调节录音音量。

参数

volume

录音信号音量可在 0 ~ 400 范围内进行调节: 0: 静音； 100: 原始音量； 400: 最大可为原始音量的 4 倍（自带溢出保护）。

返回

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

调节播放人声的音量。

参数

volume

播放音量可在 0 ~ 400 范围内进行调节： 0: 静音； 100: 原始音量； 400: 最大可为原始音量的 4 倍（自带溢出保护）。

返回

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

打开直播场景下与 Agora Web SDK 的互通。

注解

• 该方法仅适用于直播模式。通信模式默认打开与 Web SDK 的互通。
• 如果有用户通过 Web SDK 加入频道，请确保调用该方法，否则 Web 端用户看 Native 端的画面会是黑屏。

参数

enabled

true: 打开互通； false: 关闭互通（默认）。

返回

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

设置弱网条件下发布的音视频流回退选项。

网络不理想的环境下，直播音视频的质量都会下降。使用该接口并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2) 后，SDK 会在上行弱网且音视频质量严重受影响时，自动关断视频流，从而保证或提高音频质量。同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。当本地推流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发本地发布的媒体流已回退为音频流 onLocalPublishFallbackToAudioOnly 回调。

注解

旁路推流场景下，设置本地推流回退为 Audio-only 可能会导致远端的 CDN 用户听到声音的时间有所延迟。因此在有旁路推流的场景下，Agora 建议不开启该功能。

参数

option

本地推流回退处理选项： STREAM_FALLBACK_OPTION_DISABLED (0)：（默认）上行网络较弱时，不对音视频流作回退处理，但不能保证音视频流的质量 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2)：上行网络较弱时只发布音频流

返回

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

设置弱网条件下订阅的音视频流的回退选项。

默认 option 为 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1) 。如果你使用本方法并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2)，SDK 会在下行弱网且音视频质量严重受影响时，将视频流切换为小流，或关断视频流，从而保证或提高音频质量。同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。 当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发 onRemoteSubscribeFallbackToAudioOnly 回调。

参数

option

详见 STREAM_FALLBACK_OPTIONS 。

返回

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

切换前置/后置摄像头

注解

该方法仅适用于 Android 和 iOS 平台。

返回

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

设置默认的语音路由

该方法设置接收到的语音从听筒或扬声器出声。如果用户不调用本方法，语音默认从听筒出声。

各频道模式下默认的语音路由：

• 语音通话：听筒
• 视频通话：扬声器。如果有用户在频道中使用 disableVideo 、 muteLocalVideoStream 或 muteAllRemoteVideoStreams 方法关闭视频，则语音路由会自动切换回听筒。
• 直播：扬声器
• 游戏语音：扬声器

注解

• 该方法仅适用于 Android 和 iOS 平台。
• 该方法只在纯音频模式下工作，在有视频的模式下不工作。
• 该方法需要在 joinChannel 前设置，否则不生效。如需在加入频道后更改默认语音路由，请调用 setEnableSpeakerphone 方法。

参数

defaultToSpeaker

设置默认的语音路由 true: 从扬声器出声 false: （默认）从听筒出声

返回

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

启用/关闭扬声器播放

该方法设置是否将语音路由到扬声器（外放）。

该方法设置是否将语音路由设到扬声器（外放）。 你可以在 setDefaultAudioRouteToSpeakerphone 方法中查看默认的语音路由。

注解

• 该方法仅适用于 Android 和 iOS 平台。
• 请确保在调用此方法前已调用过 joinChannel 方法。
• 调用该方法后，SDK 将返回 onAudioRouteChanged 回调提示状态已更改。
• 使用耳机的时候调用该方法不会生效。

参数

speakerOn

设置是否切换语音路由到扬声器（外放）： true: 切换到外放 false: 切换到听筒

返回

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

设置耳返音量

注解

该方法仅适用于 Android 和 iOS 平台。

参数

volume

设置耳返音量，取值范围在 [0,100]。默认值为 100

返回

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

查询扬声器启用状态

注解

该方法仅适用于 Android 和 iOS 平台。

返回

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

设置 SDK 对 Audio Session 的控制权限

该接口可以在任意时候调用，可以在任意时候通过该方法把控制权交还给 SDK。

注解

• 该方法仅适用于 iOS 平台。
• 该方法限制 Agora SDK 对 Audio Session 的操作权限。在默认情况下，SDK 和 App 对 Audio Session 都有控制权，但某些场景下，App 会希望限制 Agora SDK 对 Audio Session 的控制权限，而使用其他应用或第三方组件对 Audio Session 进行操控。调用该方法可以实现该功能。
• 一旦调用该方法限制了 Agora SDK 对 Audio Session 的控制权限， SDK 将无法对 Audio Session 进行相关设置，而需要用户自己或第三方组件进行维护。

参数

restriction

Agora SDK 对 Audio Session 的控制权限，详见: AUDIO_SESSION_OPERATION_RESTRICTION 。该 restriction 为 Bit Mask，每个 Bit 对应一个权限。

返回

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

开启声卡采集

启用声卡采集功能后，声卡播放的声音会被合到本地音频流中，从而可以发送到远端。

注解

• 该方法仅适用于 macOS 和 Windows 平台。
• macOS 系统默认声卡不支持采集功能，如需开启此功能需要 App 自己启用一个虚拟声卡，并将该虚拟声卡的名字作为 deviceName 传入 SDK。 Agora 测试并推荐 soundflower 作为虚拟声卡。

参数

enabled	设置是否开启声卡采集： true: 开启声卡采集 false: （默认）关闭声卡采集
deviceName	声卡的设备名。默认设为 NULL，即使用当前声卡采集。 如果用户使用虚拟声卡，如 “Soundflower”，可以将虚拟声卡名称 “Soundflower” 作为参数，SDK 会找到对应的虚拟声卡设备，并开始采集。

通过屏幕 ID 共享屏幕。

共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕 ID。

注解

该方法仅适用于 macOS。

参数

displayId	指定待共享的屏幕 ID。开发者需要通过该参数指定你要共享的那个屏幕。关于如何获取屏幕 ID，请参考 共享屏幕。
regionRect	（可选）指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见: Rectangle 。如果设置的共享区域超出了屏幕的边界，则只共享屏幕视窗内的内容；如果宽或高为 0，则共享整个屏幕。
captureParams	屏幕共享的编码参数配置。详见: ScreenCaptureParameters 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败:
  • ERR_INVALID_STATE: 屏幕共享状态无效。可能有屏幕或窗口正在共享中，请调用 stopScreenCapture 停止共享。
  • ERR_INVALID_ARGUMENT: 传入的参数无效。

通过指定区域共享屏幕。

共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕区域。

参数

screenRect	指定待共享的屏幕相对于虚拟屏的位置。关于如何获取屏幕位置，请参考 共享屏幕。
regionRect	(可选）指定待共享区域相对于整个屏幕屏幕的位置。如不填，则表示共享整个屏幕。详见: Rectangle 。 如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕。
captureParams	屏幕共享的编码参数配置。详见: ScreenCaptureParameters 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败:
  • #ERR_INVALID_STATE: 屏幕共享状态无效。可能有屏幕或窗口正在共享中，请调用 stopSstopScreenCapturecreenCapture 停止共享。
  • ERR_INVALID_ARGUMENT: 传入的参数无效。

通过窗口 ID 共享窗口。

共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。

参数

windowId	指定待共享的窗口 ID。关于如何获取窗口 ID，请参考 共享屏幕。
regionRect	（可选）指定待共享的区域相对于整个窗口的位置。如不填，则表示共享整个窗口。详见: Rectangle 。如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容；如果宽或高为 0，则共享整个窗口。
captureParams	屏幕共享的编码参数配置。详见: ScreenCaptureParameters 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败:
  • ERR_INVALID_STATE: 屏幕共享状态无效。可能有屏幕或窗口正在共享中，请调用 stopScreenCapture 停止共享。
  • ERR_INVALID_ARGUMENT: 传入的参数无效。

设置屏幕共享内容类型。

设置屏幕共享的内容类型。Agora SDK 会根据不同的内容类型，使用不同的算法对共享效果进行优化。如果不调用该方法，SDK 会将屏幕共享的内容默认为 CONTENT_HINT_NONE ，即无指定的内容类型。

参数

contentHint

指定屏幕共享的内容类型。详见: VideoContentHint 。

返回

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

更新屏幕共享的编码参数配置。

参数

captureParams

屏幕共享的编码参数配置。详见: ScreenCaptureParameters 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败:
  • ERR_NOT_READY: 如果当前没有共享的屏幕，会返回该错误码。

更新屏幕共享区域。

参数

regionRect

待共享区域相对于整个屏幕或窗口的位置，如不填，则表示共享整个屏幕或窗口。详见: Rectangle 。

如果设置的共享区域超出了屏幕或窗口的边界，则只共享屏幕或窗口内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕或窗口。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败:
  • ERR_NOT_READY: 如果当前没有共享的屏幕，会返回该错误码。

停止屏幕共享。

返回

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

DEPRECATED 开始屏幕共享。

该方法自 v2.4.0 起废弃，请使用以下方法作为替代：

• startScreenCaptureByDisplayId
• startScreenCaptureByScreenRect
• startScreenCaptureByWindowId

该方法共享整个屏幕，指定窗口，或指定区域:

• 共享整个屏幕 : 将 windowId 设为 0，且将 rect 设为 NULL。
• 共享指定窗口 : 将 windowId 设为非 0，每个窗口都有一个非 0 的 windowId。
• 共享指定区域 : 将 windowId 设为 0，且将 rect 设为非 NULL。在这个情况下，你可以共享指定区域，例如你可以拖动鼠标选中要共享的区域，但这个逻辑你由你自己实现的。这里的共享指定区域指的是共享整个屏幕里的某个区域。目前暂不支持共享指定窗口里的指定区域。

注解

当开启屏幕共享功能时，captureFreq 参数为共享屏幕的帧率，值区间为 1 到 15 fps(必填)。无论你开启的是上述哪个功能，执行成功时均返回 0，执行失败时返回错误代码。

参数

windowId	共享屏幕区域。 详见: WindowIDType。
captureFreq	共享屏幕的帧率，必须设置，范围是 1 到 15 fps。
rect	当 windowsId 设为 0 时该参数有效；当你将 rect 设为 NULL 时，整个屏幕被共享。
bitrate	共享屏幕的码率。

返回

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

DEPRECATED 更新屏幕共享区域。

参数

rect	待共享区域相对于整个屏幕的位置，如不填，则表示共享整个屏幕。 详见: Rect。 如果设置的共享区域超出了屏幕或窗口的边界，则只共享屏幕或窗口内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕或窗口。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败:
  • ERR_NOT_READY: 如果当前没有共享的屏幕，会返回该错误码。

获取当前通话 ID。

客户端在每次 joinChannel 后会生成一个对应的 callId，标识该客户端的此次通话。有些方法如 rate 、 complain 需要在通话结束后调用，向 SDK 提交反馈，这些方法必须指定 CallId 参数。使用这些反馈方法，需要在通话过程中调用 getCallId 方法获取 CallId，在通话结束后在反馈方法中作为参数传入。

参数

callId

当前的通话 ID。

返回

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

给通话评分。

该方法能够让用户为通话评分，一般在通话结束后调用。

参数

callId	通话 getCallId 函数获取的通话 ID。
rating	给通话的评分，最低 1 分，最高 5 分。如超过这个范围，SDK 会返回 ERR_INVALID_ARGUMENT (2) 错误。
description	(非必选项) 给通话的描述，可选，长度应小于 800 字节。

返回

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

投诉通话质量。

该方法让用户就通话质量进行投诉。一般在通话结束后调用。

参数

callId	通话 getCallId 函数获取的通话 ID。
description	(非必选项) 给通话的描述，可选，长度应小于 800 字节。

返回

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

查询 SDK 版本号。

参数

build

编译号。

返回

当前的 SDK 版本号，格式为字符串，如 2.4.0。

启动网络测试。

该方法启用网络连接质量测试，用于检测用户目前的网络接入质量（上行网络质量）。默认该功能为关闭状态。该方法主要用于以下场景:

• 用户加入频道前。
• 直播模式下，当用户角色由观众切换为主播前。

启用该方法均会消耗网络流量，影响通话质量。用户必须在收到 onLastmileQuality 回调后须调用 disableLastmileTest 停止测试，再加入频道或切换为主播。

注解

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

返回

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

关闭网络测试。

返回

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

开始通话前网络质量探测。

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

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

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

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

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

注解

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

参数

config

Last mile 网络探测配置，详见 LastmileProbeConfig 。

返回

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

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

返回

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

获取警告或错误描述。

参数

code	onWarning 或 onError 提供的警告码或错误码。

返回

WARN_CODE_TYPE 或 ERROR_CODE_TYPE 。

启用内置加密，并设置数据加密密码。

在加入频道之前，App 需调用 setEncryptionSecret 方法指定 secret 来启用内置的加密功能，同一频道内的所有用户应设置相同的 secret。当用户离开频道时，该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空，则无法激活加密功能。

注解

• 请不要在旁路推流时调用此方法。
• 为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。

参数

secret

加密密码。

返回

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

启用内置的加密方案。

Agora Video SDK 支持内置加密方案，默认支持 AES-128-XTS。如需采用其他加密方案，可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别，请参考 AES 加密算法的相关资料。

注解

在调用本方法前，请先调用 setEncryptionSecret 启用内置加密功能。

参数

encryptionMode

加密模式： "aes-128-xts": 128 位 AES 加密，XTS 模式； "aes-128-ecb":128 位 AES 加密，ECB 模式； "aes-256-xts": 256 位 AES 加密，XTS 模式； "": 设置为空字符串时，默认使用加密方式 "aes-128-xts"。

返回

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

注册数据包观测器。

该方法注册数据包观测器 (Packet Observer)。在 Agora SDK 发送/接收（语音、视频）网络包时，会回调 IPacketObserver 定义的接口，App 可用此接口对数据做处理，例如加解密。

注解

• 处理后发送到网络的包大小不应超过 1200 字节，否则有可能发送失败。
• 若需调用此方法，需确保接收端和发送端都调用此方法，否则会出现未定义行为（例如音频无声或视频黑屏）。
• 若在直播场景下使用 CDN 推流、录制或储存，Agora 不建议调用此方法。

参数

observer

IPacketObserver 。

返回

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

创建数据流。

该方法用于创建数据流。RtcEngine 生命周期内，每个用户最多只能创建 5 个数据流。频道内数据通道最多允许数据延迟 5 秒，若超过 5 秒接收方尚未收到数据流，则数据通道会向 App 报错。

注解

将 reliable 和 ordered 同时设为 true 或 false。不要一个设为 true 另一个设为 false。

参数

streamId	数据流 ID。
reliable	true: 接收方 5 秒内会收到发送方所发送的数据，否则会收到 onStreamMessageError 回调获得相应报错信息。 false: 接收方不保证收到，就算数据丢失也不会报错。
ordered	true: 接收方 5 秒内会按照发送方发送的顺序收到数据包； false: 接收方不保证按照发送方发送的顺序收到数据包。

返回

• 0: 创建数据流成功。
• < 0: 创建数据流失败。

发送数据流。

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制：频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。 API 须对数据通道的传送速率进行控制: 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。 成功调用该方法后，远端会触发 onStreamMessage 回调，远端用户可以在该回调中获取接收到的流消息；若调用失败，远端会触发 onStreamMessageError 回调。

注解

该方法仅适用于通信模式以及直播模式下的主播用户，如果直播模式下的观众调用此方法可能会造成观众变主播。

参数

streamId	由 createDataStream 返回的数据流 ID。
data	自定义数据。
length	数据长度。

返回

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

增加旁路推流地址。

调用该方法后，SDK会在本地触发 onRtmpStreamingStateChanged 回调，报告增加旁路推流地址的状态。

注解

• 请确保在成功加入频道后才能调用该接口。
• 请确保已开通旁路推流的功能，详见前提条件。
• 该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。
• 该方法仅适用于直播模式。

参数

url	CDN 推流地址，格式为 RTMP。该字符长度不能超过 1024 字节。url 不支持中文字符等特殊字符。
transcodingEnabled	true: 转码（ 转码 是指在旁路推流时对音视频流进行转码处理后再推送到其他 RTMP 服务器。多适用于频道内有多个主播，需要进行混流、合图的场景）。如果设为 true，需先调用 setLiveTranscoding 方法。 false: 不转码。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。
  • ERR_INVALID_ARGUMENT (2): URL 为空或是长度为 0 的的字符串
  • ERR_NOT_INITIALIZED (7): 推流时未初始化引擎

删除旁路推流地址。 调用该方法后，SDK 会在本地触发 onRtmpStreamingStateChanged 回调，报告删除旁路推流地址的状态。

注解

• 该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。
• URL 不支持中文等特殊字符。
• 该方法仅适用于直播模式。

参数

url	待删除的旁路推流地址，格式为 RTMP。该字符长度不能超过 1024 字节。

返回

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

设置直播推流转码。

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 onTranscodingUpdated 回调。

注解

• 该方法仅适用于直播模式。
• 请确保已开通旁路推流的功能，详见前提条件。
• 首次调用该方法更新转码设置时，不会触发 onTranscodingUpdated 回调。

参数

transcoding

详见 LiveTranscoding 。

返回

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

DEPRECATED 添加本地视频水印。

该方法已废弃，请使用 addVideoWatermark2 作为替代。

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上，同一直播频道中的观众，旁路推流观众，甚至录制设备都能看到或采集到该水印图片。 如果你仅仅希望在旁路直播推流中添加水印，请参考 setLiveTranscoding 中描述的用法。

注解

• 在本地直播和旁路推流中，URL 的定义不同。本地直播中，URL 指本地直播视频上图片的本地绝对/相对路径；旁路推流中，URL 指旁路推流视频上图片的地址。
• 待添加图片的源文件格式必须是 PNG。如果待添加的 PNG 图片的尺寸与你该方法中设置的尺寸不一致，SDK 会对 PNG 图片进行裁剪，以与设置相符。
• 声网当前只支持在直播视频流中添加一个水印，后添加的水印会替换掉之前添加的水印。

参数

watermark

待添加在本地直播推流中的水印图片： RtcImage 。

返回

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

添加本地视频水印。

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上，同一直播频道中的观众、旁路直播观众和录制设备都能看到或采集到该水印图片。Agora 当前只支持在直播视频流中添加一个水印，后添加的水印会替换掉之前添加的水印。

水印坐标和 setVideoEncoderConfiguration 方法中的设置有依赖关系：

• 如果视频编码方向/ ORIENTATION_MODE 固定为横屏或自适应模式下的横屏，那么水印使用横屏坐标。
• 如果视频编码方向/ ORIENTATION_MODE 固定为竖屏或自适应模式下的竖屏，那么水印使用竖屏坐标。
• 设置水印坐标时，水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸，否则超出部分将被裁剪。

注解

• 你需要在调用 enableVideo 方法之后再调用本方法。
• 如果你只是在旁路直播（推流到CDN）中添加水印，你可以使用本方法或 setLiveTranscoding 方法设置水印。
• 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片：RGBA、RGB、Palette、Gray 和 Alpha_gray。
• 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致，SDK 会对 PNG 图片进行缩放或裁剪，以与设置相符。
• 如果你已经使用 startPreview 方法开启本地视频预览，那么本方法的 visibleInPreview 可设置水印在预览时是否可见。
• 如果你已经使用 setLocalVideoMirrorMode 方法设置了本地视频镜像模式，那么预览可见的水印也为镜像。

参数

watermarkUrl	待添加的水印图片的本地路径。本方法支持从本地绝对/相对路径添加水印图片。
options	待添加的水印图片的设置选项，详见 WatermarkOptions 。

返回

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

删除已添加的视频水印。

返回

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

该方法仅支持 Android 和 iOS 平台! 设置美颜效果选项。

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

参数

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

返回

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

导入在线媒体流。

注解

• 请确保已开通旁路推流的功能，详见前提条件。
• 该方法适用于 Native SDK v2.4.1 及之后的版本。

该方法将正在播放的音视频作为音视频源导入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。调用该方法后，SDK 会在本地触发 onStreamInjectedStatus 回调，报告导入在线媒体流的状态；成功导入媒体流后，该音视频流会出现在频道中，频道内所有用户都会收到 onUserJoined 回调，其中 uid 为 666。该音视频流会出现在频道中。

参数

url	添加到直播中的视频流 URL 地址。支持 RTMP、HLS、FLV 协议传输。 支持的 FLV 音频编码格式：AAC； 支持的 FLV 视频编码格式：H.264(AVC)。
config	所添加的视频流属性定义，详见: InjectStreamConfig 。

返回

• 0: 方法调用成功；
• < 0: 方法调用失败。
  • ERR_INVALID_ARGUMENT (2): 输入的 URL 为空。请重新调用该方法，并确认输入的媒体流的 URL 有效。
  • ERR_NOT_READY (3): 用户没有加入频道。
  • ERR_NOT_SUPPORTED (4): 频道非直播模式。请调用 setChannelProfile 并将频道设置为直播模式再调用该方法。
  • ERR_NOT_INITIALIZED (7): 引擎没有初始化。请确认调用该方法前已创建 IRtcEngine 对象并完成初始化。

开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。

成功调用该方法后，SDK 会触发 onChannelMediaRelayStateChanged 和 onChannelMediaRelayEvent 回调，并在回调中报告当前的跨频道媒体流转发状态和事件。

• 如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_RUNNING (2) 和 RELAY_OK (0)，且 onChannelMediaRelayEvent 回调报告 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4)， 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
• 如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_FAILURE (3)， 则表示跨频道媒体流转发出现异常。

注解

• 请在成功加入频道后调用该方法。
• 该方法仅对直播模式下的主播有效。
• 成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。

参数

configuration

跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。

返回

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

更新媒体流转发的频道。成功开始跨频道转发媒体流后，如果你希望将流转发到多个目标频道， 或退出当前的转发频道，可以调用该方法。

成功调用该方法后，SDK 会触发 onChannelMediaRelayEvent 回调， 并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7)。

注解

请在 startChannelMediaRelay 方法后调用该方法，更新媒体流转发的频道。

参数

configuration

跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。

返回

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