RtcEngine

详细描述

RtcEngine 类包含 App 调用的主要方法，调用 RtcEngine 的接口最好在同一个线程进行，不建议在不同的线程同时调用。

成员函数说明

create()

abstract synchronized RtcEngine create(Context context,String appId,IRtcEngineEventHandler handler)

创建 RtcEngine 实例。

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

注解

请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。目前 SDK 只支持每个 app 创建一个 RtcEngine 实例。

返回

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

异常

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

destroy()

static synchronized void destroy()

销毁 RtcEngine 实例。

该方法释放 AR SDK 使用的所有资源。有些 App 只在用户需要时才进行语音通话，不需要时则将资源释放出来用于其他操作，该方法对这类程序可能比较有用。只要调用了 destroy 方法，用户将无法再使用和回调该 SDK 内的其它方法。如需再次使用通信功能，必须重新调用 create 一个 RtcEngine 实例（instance)。

注解

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

• 如果需要在销毁后再次创建 RtcEngine 实例，需要等待 destroy 方法执行结束，收到返回值后才能再创建实例。

setChannelProfile()

abstract int setChannelProfile(int profile)

设置频道场景。

该方法用于设置 AR RtcEngine 频道的使用场景。RtcEngine 会针对不同的使用场景采用不同的优化策略，如通信场景偏好流畅，直播场景偏好画质。

返回

• 0：方法调用成功

• < 0：方法调用失败

注解

• 为保证实时音视频质量，我们建议相同频道内的用户必须使用同一种频道场景。
• 该方法必须在加入频道前调用，进入频道后无法再设置频道模式。

setClientRole()

abstract int setClientRole(int role)

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

在加入频道前，用户需要通过本方法设置观众（默认）或主播模式。在加入频道后，用户可以通过本方法切换用户模式。

直播场景下，如果你在加入频道后调用该方法切换用户角色，调用成功后，本地会触发 onClientRoleChanged 回调；远端会触发 onUserJoined/onUserOffline(USER_OFFLINE_BECOME_AUDIENCE) 回调。

返回

• 0：方法调用成功

• < 0：方法调用失败

joinChannel()

abstract int joinChannel(String token,String channelName,String optionalInfo,int optionalUid )

加入频道。

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

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

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

注解

频道内每个用户的 UID 必须是唯一的。如果将 UID 设为 ""（空字符串），系统将自动分配一个 UID。如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 UID 是不同的。

警告

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

返回

• 0：方法调用成功

• < 0：方法调用失败

• ERR_INVALID_ARGUMENT(-2)

• ERR_NOT_READY(-3)

• ERR_REFUSED(-5)。

switchChannel()

abstract int switchChannel(String token,String channelName )

快速切换直播频道。

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

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

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

leaveChannel()

abstract int leaveChannel()

离开频道。

离开频道，即挂断或退出通话。 当调用 joinChannel API 方法后，必须调用 leaveChannel 结束通话，否则无法开始下一次通话。 不管当前是否在通话中，都可以调用 leaveChannel，没有副作用。该方法会把会话相关的所有资源释放掉。该方法是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，SDK 会触发 onLeaveChannel 回调。

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

注解

如果你调用了 leaveChannel 后立即调用 destroy 方法，SDK 将无法触发 onLeaveChannel 回调。

返回

• 0：方法调用成功

• < 0：方法调用失败

renewToken()

abstract int renewToken(String token)

更新 Token。

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

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

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

返回

• 0：方法调用成功

• < 0：方法调用失败

getConnectionState()

abstract int getConnectionState()

获取当前网络连接状态。

返回

当前的网络连接状态：

• CONNECTION_STATE_DISCONNECTED(1)：网络连接断开

• CONNECTION_STATE_CONNECTING(2)：建立网络连接中

• CONNECTION_STATE_CONNECTED(3)：网络已连接

• CONNECTION_STATE_RECONNECTING(4)：重新建立网络连接中

• CONNECTION_STATE_FAILED(5)：网络连接失败

enableAudio()

abstract int enableAudio()

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

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

disableAudio()

abstract int disableAudio()

关闭音频模块。

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

setAudioProfile()

abstract int setAudioProfile(int profile,int scenario )

设置音频编码配置。

注解

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

adjustRecordingSignalVolume()

abstract int adjustRecordingSignalVolume(int volume)

调节录音音量。

返回

• 0：方法调用成功

• <0：方法调用失败

adjustPlaybackSignalVolume()

abstract int adjustPlaybackSignalVolume(int volume)

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

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

adjustUserPlaybackSignalVolume()

abstract int adjustUserPlaybackSignalVolume(String uid,String volume )

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

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

注解

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

返回

• 0：方法调用成功。

• < 0：方法调用失败。

enableAudioVolumeIndication()

abstract int enableAudioVolumeIndication(int interval,int smooth,boolean report_vad )

启用说话者音量提示。

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

返回

• 0：方法调用成功

• < 0：方法调用失败

enableLocalAudio()

abstract int enableLocalAudio(boolean enabled)

开/关本地音频采集。

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

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

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

muteLocalAudioStream()

abstract int muteLocalAudioStream(boolean muted)

停止/恢复发送本地音频流。

静音/取消静音。该方法用于允许/禁止往网络发送本地音频流。

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

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

muteRemoteAudioStream()

abstract int muteRemoteAudioStream(String uid,boolean muted )

停止/恢复接收指定音频流。

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

muteAllRemoteAudioStreams()

abstract int muteAllRemoteAudioStreams(boolean muted)

停止/恢复接收所有音频流。

返回

• 0：方法调用成功

• < 0：方法调用失败

setDefaultMuteAllRemoteAudioStreams()

abstract int setDefaultMuteAllRemoteAudioStreams(boolean muted)

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

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteAudioStreams(true)， 会接收不到后面加入频道的用户的音频流。

注解

停止接收音频流后，如果想要恢复接收，请调用 muteRemoteAudioStream(false)，并指定你想要接收的远端用户的 ID。 如果想恢复接收多个用户的音频流，则需要多次调用 muteRemoteAudioStream。 setDefaultMuteAllRemoteAudioStreams(false) 只能恢复接收设置后加入频道的用户的音频流。

返回

• 0：方法调用成功

• < 0：方法调用失败

enableVideo()

abstract int enableVideo()

启用视频模块。

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

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

注解

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

返回

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

disableVideo()

abstract int disableVideo()

关闭视频模块。

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

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

注解

• 该方法设置的是内部引擎为禁用状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。

• 该方法重置整个引擎，响应速度较慢，因此 我们 建议使用如下方法来控制视频模块：

• enableLocalVideo：是否启动摄像头采集并创建本地视频流

• muteLocalVideoStream：是否发布本地视频流

• muteRemoteVideoStream：是否接收并播放远端视频流

• muteAllRemoteVideoStreams：是否接收并播放所有远端视频流

返回

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

setVideoEncoderConfiguration()

abstract int setVideoEncoderConfiguration(VideoEncoderConfiguration config)

设置视频编码属性。

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

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

返回

• 0：方法调用成功

• < 0：方法调用失败

setCameraCapturerConfiguration()

abstract int setCameraCapturerConfiguration(CameraCapturerConfiguration config)

设置摄像头的采集偏好。

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

• 使用裸数据自采集接口时，如果 SDK 输出的分辨率和帧率高于 setVideoEncoderConfiguration 中指定的参数，在后续处理视频帧的时候，比如美颜功能时， 会需要更高的 CPU 及内存，容易导致性能问题。在这种情况下，我们推荐将摄像头采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1)，避免性能问题

• 如果没有本地预览功能或者对预览质量没有要求，我们推荐将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1)，以优化 CPU 和内存的资源分配

• 如果用户希望本地预览视频比实际编码发送的视频清晰，可以将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PREVIEW(2)

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

setupLocalVideo()

abstract int setupLocalVideo(VideoCanvas local)

初始化本地视图。

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

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

setupRemoteVideo()

abstract int setupRemoteVideo(VideoCanvas remote)

初始化远端用户视图。

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

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

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

setLocalRenderMode()

abstract int setLocalRenderMode(int renderMode,int mirrorMode )

更新本地视图显示模式。

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

注解

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

返回

• 0：方法调用成功。

• < 0：方法调用失败。

setRemoteRenderMode()

abstract int setRemoteRenderMode(String uid,int renderMode,int mirrorMode )

更新远端视图显示模式。

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

注解

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

返回

• 0：方法调用成功。

• < 0：方法调用失败。

CreateRendererView()

static TexutureView CreateRendererView(Context context)

创建渲染视图。

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

注解

• 请在主线程调用该方法。

返回

TexutureView

startPreview()

abstract int startPreview()

开启视频预览。

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

调用 enableVideo 开启视频功能

调用 setupLocalVideo 设置预览窗口及属性

注解

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

返回

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

stopPreview()

abstract int stopPreview()

停止视频预览。

返回

• 0：方法调用成功

• <0：方法调用失败

enableLocalVideo()

abstract int enableLocalVideo(boolean enabled)

开/关本地视频采集。

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

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

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

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

muteLocalVideoStream()

abstract int muteLocalVideoStream(boolean muted)

停止/恢复发送本地视频流。

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

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

muteRemoteVideoStream()

abstract int muteRemoteVideoStream(String uid,boolean muted )

停止/恢复接收指定视频流。

注解

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

返回

• 0：方法调用成功

• < 0：方法调用失败

muteAllRemoteVideoStreams()

abstract int muteAllRemoteVideoStreams(boolean muted)

停止/恢复接收所有视频流。

返回

• 0：方法调用成功

• < 0：方法调用失败

setDefaultMuteAllRemoteVideoStreams()

abstract int setDefaultMuteAllRemoteVideoStreams(boolean muted)

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

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteVideoStreams(true)， 会接收不到后面加入频道的用户的音频流。

注解

停止接收视频流后，如果想要恢复接收，请调用 muteRemoteVideoStream(false)，并指定你想要接收的远端用户的 ID。 如果想恢复接收多个用户的视频流，则需要多次调用 muteRemoteVideoStream。 setDefaultMuteAllRemoteVideoStreams(false) 只能恢复接收设置后加入频道的用户的视频流。

返回

• 0：方法调用成功

• < 0：方法调用失败

setDefaultAudioRoutetoSpeakerphone()

abstract int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeaker)

设置默认的音频播放路由。

该方法设置接收到的语音从听筒或扬声器出声。如果用户不调用本方法，则语音默认从听筒出声。 如果你想要在加入频道后修改语音路由，可以使用 setEnableSpeakerphone.

各场景下默认的语音路由：

通信场景：

• 语音通话，默认从听筒出声。
• 视频通话，默认从扬声器出声。如果有用户在频道中使用 disableVideo 或 muteLocalVideoStream 和 muteAllRemoteVideoStreams 关闭视频，则语音路由会自动切换回听筒。

直播场景

• 扬声器

注解

• 该方法仅适用于通信场景。

• 该方法需要在加入频道前设置，否则不生效。

返回

• 0：方法调用成功

• < 0：方法调用失败

setEnableSpeakerphone()

abstract int setEnableSpeakerphone(boolean enabled)

启用/关闭扬声器播放。

该方法设置是否将语音路由设到扬声器（外放）。调用该方法后，SDK 将触发 onAudioRouteChanged 回调提示状态已更改。

注解

• 请确保在调用此方法前已调用过 joinChannel 方法。
• setAudioProfile 中 scenario 的设置会影响 setEnableSpeakerphone 的行为。setEnableSpeakerphone 不生效的情况如下：
• 当 scenario 为 AUDIO_SCENARIO_GAME_STREAMING 时，所有用户都无法切换音频播放路由。
• 当 scenario 为 AUDIO_SCENARIO_DEFAULT 或 AUDIO_SCENARIO_SHOWROOM 时，直播场景中的观众无法切换音频播放路由，且当频道中只有一个主播时，该主播也无法切换音频播放路由。
• 当 scenario 为 AUDIO_SCENARIO_EDUCATION 时，直播场景中的观众无法切换音频播放路由。

返回

• 0：方法调用成功

• < 0：方法调用失败

isSpeakerphoneEnabled()

abstract boolean isSpeakerphoneEnabled()

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

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

返回

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

enableInEarMonitoring()

abstract int enableInEarMonitoring(boolean *enabled*)

开启耳返功能。

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

返回

• 0：方法调用成功

• < 0：方法调用失败

setInEarMonitoringVolume()

abstract int setInEarMonitoringVolume(int volume)

设置耳返音量。

返回

• 0：方法调用成功

• < 0：方法调用失败

startAudioMixing()

abstract int startAudioMixing(String filePath,boolean loopback,boolean replace,int cycle)

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

该方法指定本地或在线音频文件来和麦克风采集的音频流进行混音或替换。替换是指用音频文件替换麦克风采集的音频流。该方法可以选择是否让对方听到本地播放的音频，并指定循环播放的次数。

注解

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

返回

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

stopAudioMixing()

abstract int stopAudioMixing()

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

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

返回

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

pauseAudioMixing

abstract int pauseAudioMixing()

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

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

返回

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

resumeAudioMixing

abstract int resumeAudioMixing()

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

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

返回

• 0：方法调用成功

• < 0：方法调用失败

adjustAudioMixingVolume

abstract int adjustAudioMixingVolume(int volume)

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

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

注解

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

返回

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

adjustAudioMixingPlayoutVolume

abstract int adjustAudioMixingPlayoutVolume(int volume)

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

返回

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

adjustAudioMixingPublishVolume

int adjustAudioMixingPublishVolume(int volume)

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

返回

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

getAudioMixingPlayoutVolume

abstract int getAudioMixingPlayoutVolume()

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

返回

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

getAudioMixingPublishVolume

abstract int getAudioMixingPublishVolume()

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

返回

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

getAudioMixingDuration

abstract int getAudioMixingDuration()

获取音乐文件的时长。

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

返回

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

getAudioMixingCurrentPosition

abstract int getAudioMixingCurrentPosition()

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

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

返回

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

setAudioMixingPosition

abstract int setAudioMixingPosition(int pos)

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

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

返回

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

getAudioEffectManager()

abstract IAudioEffectManager getAudioEffectManager()

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

返回

IAudioEffectManager

startAudioRecording()

abstract int startAudioRecording(String filePath,int sampleRate,int quality )

开始客户端录音。

调用该方法后，你可以录制频道内所有用户的音频，并得到一个包含所有用户声音的录音文件。录音文件格式可以为：

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

注解

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

返回

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

stopAudioRecording()

abstract int stopAudioRecording()

停止客户端录音。

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

返回

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

setVideoSource()

abstract int setVideoSource(IVideoSource source)

设置自定义视频源。

实时通讯过程中，AR SDK 通常会启动默认的视频输入设备，即内置的摄像头，进行视频推流。当需要自定义视频设备时，App 可以先通过 IVideoSource 接口自定义视频源，然后调用该方法将自定义的视频源加入到 SDK 中。

setExternalVideoSource()

abstract int pushExternalAudioFrame(byte[] data,long timestamp)

配置外部视频源。

pushExternalVideoFrame()

abstract boolean pushExternalVideoFrame (ARVideoFrame   frame   )

推送外部视频帧。

该方法主动将视频帧数据用ARVideoFrame 类封装后传递给 SDK。请确保在你调用本方法前已调用 setExternalVideoSource，并将参数 pushMode 设为 true，不然调用本方法后会一直报错。

返回

• true：该帧推送成功
• false：该帧推送不成功

setExternalAudioSource()

abstract int setExternalAudioSource(boolean enabled,int sampleRate,int channels)

设置外部音频采集参数。

请在 joinChannel 和 startPreview 前调用该方法。

返回

• 0：方法调用成功

• < 0：方法调用失败

pushExternalAudioFrame()

abstract int pushExternalAudioFrame(byte[] data,long timestamp )

推送外部音频帧。

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

返回

• 0：方法调用成功

• < 0：方法调用失败

setExternalAudioSink()

abstract int setExternalAudioSink(boolean enabled, int  sampleRate, int channels )

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

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

返回

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

pullPlaybackAudioFrame()

abstract int pullPlaybackAudioFrame(byte[]  data, int lengthInByte  )

拉取外部音频数据。

使用该方法前，你需要调用 setExternalAudioSink(enabled: true) 方法通知 App 开启并设置外部渲染。

该方法需要在加入频道后调用。 调用该方法后，app 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。

返回

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

enableDualStreamMode()

abstract int enableDualStreamMode(boolean enabled)

开/关视频双流模式。

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

返回

• 0：方法调用成功

• < 0：方法调用失败

setRemoteVideoStreamType()

abstract int setRemoteVideoStreamType(String uid,int streamType )

设置订阅的视频流类型。

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

正常情况下，用户默认接收大流。如需节约带宽和计算资源，则可以调用该方法动态调整对应远端视频流的大小。 SDK 会根据该方法中的设置，切换大小流。

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

返回

• 0：方法调用成功

• < 0：方法调用失败

setRemoteDefaultVideoStreamType()

abstract int setRemoteDefaultVideoStreamType(int streamType)

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

返回

• 0：方法调用成功

• < 0：方法调用失败

switchCamera()

abstract int switchCamera()

切换前置/后置摄像头。

返回

• 0：方法调用成功

• < 0：方法调用失败

isCameraZoomSupported()

abstract boolean isCameraZoomSupported()

检测设备是否支持摄像头缩放功能。

返回

• true：设备支持相机缩放功能

• false：设备不支持相机缩放功能

isCameraTorchSupported()

abstract boolean isCameraTorchSupported()

检测设备是否支持闪光灯常开。

注解

一般情况下，App 默认开启前置摄像头，因此如果你的前置摄像头不支持闪光灯常开，直接使用该方法会返回 false。如果需要检查后置摄像头是否支持闪光灯常开，需要先使用 switchCamera 切换摄像头，再使用该方法。

返回

• true：设备支持闪光灯常开

• false：设备不支持闪光灯常开

isCameraFocusSupported()

abstract boolean isCameraFocusSupported()

检测设备是否支持手动对焦功能。

返回

• true：设备支持手动对焦功能

• false：设备不支持手动对焦功能

isCameraExposurePositionSupported()

abstract boolean isCameraExposurePositionSupported()

检测设备是否支持手动曝光功能。

返回

• true：设置支持手动曝光功能

• false：设备不支持手动曝光功能

isCameraAutoFocusFaceModeSupported()

abstract boolean isCameraAutoFocusFaceModeSupported()

检测设备是否支持人脸对焦功能。

返回

• true：设备支持人脸对焦功能

• false：设备不支持人脸对焦功能

setCameraZoomFactor()

abstract int setCameraZoomFactor setCameraZoomFactor(float factor)

设置摄像头缩放比例。

返回

• 方法调用成功：返回设置的 Factor 值

• 方法调用失败：返回值 < 0-

getCameraMaxZoomFactor()

abstract float getCameraMaxZoomFactor()

获取摄像头支持最大缩放比例。

返回

• 该相机支持的最大缩放比例。

setCameraFocusPositionInPreview()

abstract int setCameraFocusPositionInPreview(float positionX,float positionY )

设置手动对焦位置，并触发对焦。

成功调用该方法后，本地会触发 onCameraFocusAreaChanged 回调。

返回

• 0：方法调用成功

• < 0：方法调用失败

setCameraExposurePosition()

abstract int setCameraExposurePosition(float positionXinView,float positionYinView )

设置手动曝光位置。

成功调用该方法后，本地会触发 onCameraExposureAreaChanged 回调。

返回

• 0：方法调用成功

• < 0：方法调用失败

setCameraTorchOn()

abstract int setCameraTorchOn(boolean isOn)

设置是否打开闪光灯。

返回

• 0：方法调用成功

• < 0：方法调用失败

setCameraAutoFocusFaceModeEnabled()

abstract int setCameraAutoFocusFaceModeEnabled(boolean enabled)

设置是否开启人脸对焦功能。

getCallId()

abstract String getCallId()

获取通话 ID。

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

返回

通话 ID。

getSdkVersion()

static String getSdkVersion()

查询 SDK 版本号。

返回

• 当前的 SDK 版本号

setLogFile()

abstract int setLogFile(String filePath)

设置日志文件。

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

注解

如需调用本方法，请在调用 create 方法初始化 RtcEngine 对象后立即调用，否则可能造成输出日志不完整。

返回

• 0：方法调用成功

• < 0：方法调用失败

setLogFilter()

abstract int setLogFilter(int filter)

设置日志过滤器。

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

返回

0：方法调用成功

< 0：方法调用失败

setLogFileSize()

abstract int setLogFileSize(int fileSizeInKBytes)

设置日志文件大小。

设置 SDK 输出的日志文件大小，单位为 KB。

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

返回

• 0：方法调用成功

• < 0：方法调用失败，有可能是因为传入的参数无效

getErrorDescription()

static String getErrorDescription(int error)

获取错误码或警告码描述。

返回

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

startChannelMediaRelay()

abstract int startChannelMediaRelay (ChannelMediaRelayConfiguration     channelMediaRelayConfiguration) 

开始跨频道媒体流转发。

该方法可用于实现跨频道媒体流转发。

成功调用该方法后，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)，则表示跨频道媒体流转发出现异常。

注解

• 跨频道媒体流转发功能需要提交工单联系技术支持开通。

• 该功能不支持 String 型 UID。

• 请在成功加入频道后调用该方法。

• 该方法仅适用于直播场景下的主播。

• 成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。

参数

返回

• 0：方法调用成功

• < 0：方法调用失败

stopChannelMediaRelay

abstract int stopChannelMediaRelay

停止跨频道媒体流转发。

一旦停止，主播会退出所有目标频道。

成功调用该方法后，SDK 会触发 onChannelMediaRelayStateChanged 回调。如果报告 RELAY_STATE_IDLE(0) 和 RELAY_OK(0)，则表示已停止转发媒体流。

注解

• 如果该方法调用不成功，SDK 会触发 onChannelMediaRelayStateChanged 回调，并报告状态码 RELAY_ERROR_SERVER_NO_RESPONSE(2) 或 RELAY_ERROR_SERVER_CONNECTION_LOST(8)。你可以调用 leaveChannel 方法离开频道，跨频道媒体流转发会自动停止。

返回

• 0：方法调用成功

• < 0：方法调用失败

updateChannelMediaRelay

abstract int updateChannelMediaRelay(ChannelMediaRelayConfiguration channelMediaRelayConfiguration) 

更新媒体流转发的频道。

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

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

注解

• 请在 startChannelMediaRelay 方法后调用该方法，更新媒体流转发的频道。
• 跨频道媒体流转发最多支持 4 个目标频道。如果直播间里已经有 4 个频道了，你可以在调用该方法之前，调用 ChannelMediaRelayConfiguration 类中的 removeDestChannelInfo 方法移除不需要的频道。

参数

返回

• 0：方法调用成功

• < 0：方法调用失败

addInjectStreamUrl()

abstract int addInjectStreamUrl (String url,LiveInjectStreamConfig  config) 

输入在线媒体流。 该方法通过在服务端拉取视频流并发送到频道中，将正在播出的视频输入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。

调用该方法后，SDK 会在本地触发 onStreamInjectedStatus 回调，报告输入在线媒体流的状态； 成功输入媒体流后，该音视频流会出现在频道中，频道内所有用户都会收到 onUserJoined 回调，其中 uid 为 "share666"。

注解

• 调用该方法前，请确保已开通旁路推流的功能。
• 该方法仅适用于直播场景中的主播用户。
• 频道内同一时间只允许输入一个在线媒体流。

返回

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

removeInjectStreamUrl

abstract int removeInjectStreamUrl(String url)

删除输入的在线媒体流。

成功删除后，会触发 onUserOffline 回调，其中 uid 为 "share666"。

返回

• 0: 方法调用成功。

• < 0: 方法调用失败。

addPublishStreamUrl

abstract int addPublishStreamUrl(String url,boolean transcodingEnabled) 

增加旁路推流地址。

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

注解

• 该方法仅适用于直播场景。
• 请确保在成功加入频道后再调用该接口。
• 请确保已开通旁路推流的功能。
• 该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。

返回

• 0: 方法调用成功。

• < 0: 方法调用失败。

removePublishStreamUrl

abstract int removePublishStreamUrl(String url) 

删除旁路推流地址。

该方法用于删除旁路推流过程中已经设置的 RTMP 推流地址。调用该方法后，SDK 会在本地触发 rtmpStreamingChangedToState 回调，报告删除旁路推流地址的状态。

注解

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

返回

• 0: 方法调用成功。

• < 0: 方法调用失败。

setLiveTranscoding

abstract int setLiveTranscoding (LiveTranscoding transcoding    )

设置直播转码。

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

注解

• 该方法仅适用于直播场景。
• 请确保已开通 CDN 旁路推流的功能。
• 首次调用该方法更新转码设置时，不会触发 rtcEngineTranscodingUpdated 回调。

返回

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

takeSnapshot

public abstract int takeSnapshot(String uid, String filePath);

获取视频截图。

该方法用于对指定用户的视频流进行截图，生成一张 JPG 格式的图片，并保存至指定的路径。

该方法是异步操作，调用返回时 SDK 并没有真正获取截图。成功调用该方法后，SDK 会触发 onSnapshotTaken回调报告截图是否成功和获取截图的详情。

注解

filePath示例

• Android: /storage/emulated/0/Android/data/<package name>/files/example.jpg

• 请确保目录存在且可写

返回

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

addVideoWatermark

public abstract int addVideoWatermark(RtcImage watermark);

该方法将一张图片作为水印添加到本地发布的直播视频流上，同一直播频道中的用户，旁路推流观众，甚至采集设备都能看到或采集到该水印图片。

返回值

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

clearVideoWatermarks

public abstract int clearVideoWatermarks();

删除添加的水印

返回值

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