RtcEngine

public abstract class com.ss.video.rtc.engine.RtcEngine

RtcEngine接口

成员变量

静态函数

成员函数

变量说明

VIDEO_MIRROR_MODE_AUTO

public static final int com.ss.video.rtc.engine.RtcEngine.VIDEO_MIRROR_MODE_AUTO = 0;

默认镜像模式，即由 SDK 决定镜像模式

VIDEO_MIRROR_MODE_ENABLED

public static final int com.ss.video.rtc.engine.RtcEngine.VIDEO_MIRROR_MODE_ENABLED = 1;

启用镜像模式

VIDEO_MIRROR_MODE_DISABLED

public static final int com.ss.video.rtc.engine.RtcEngine.VIDEO_MIRROR_MODE_DISABLED = 2;

关闭镜像模式

函数说明

create

public static synchronized RtcEngine com.ss.video.rtc.engine.RtcEngine.create(
    Context context,
    String appId,
    IRtcEngineEventHandler handler)

创建引擎对象
此方法应该作为正常 SDK 流程中的第一步操作，通过创建一个引擎实例，来使用 SDK 的其他能力

传入参数

返回值

• RtcEngine 创建成功。返回一个可用的 RtcEngineImpl 实例
• null so 加载失败，创建失败。返回 null

注意

• 调用者应注意保持 handler 的生命周期必须大于 RtcEngine 的生命周期，即 handler 必须在调用 create 之前创建，在调用 destroy 之后销毁
• 连续多次调用 create 方法将不会创建新的 RtcEngine，只有第一次调用 会创建一个新的实例，并设置相关的 handler，后续的调用将不会更新 handler，而是直接返回第一次创建的 RtcEngine 对象
• 在调用 destroy 之后会销毁 RtcEngine，再次调用 create 方法则会重新创建一个全新的 RtcEngine 对象

create

public static synchronized RtcEngine com.ss.video.rtc.engine.RtcEngine.create(
    Context context,
    String appId,
    IRtcEngineEventHandler handler,
    Object eglContext)

创建引擎对象
此方法应该作为正常 SDK 流程中的第一步操作，通过创建一个引擎实例，来使用 SDK 的其他能力

传入参数

返回值

• RtcEngine 创建成功。返回一个可用的 RtcEngineImpl 实例
• null so 加载失败，创建失败。返回 null

注意

• 调用者应注意保持 handler 的生命周期必须大于 RtcEngine 的生命周期，即 handler 必须在调用 create 之前创建，在调用 destroy 之后销毁
• 连续多次调用 create 方法将不会创建新的 RtcEngine，只有第一次调用 会创建一个新的实例，并设置相关的 handler，后续的调用将不会更新 handler，而是直接返回第一次创建的 RtcEngine 对象
• 在调用 destroy 之后会销毁 RtcEngine，再次调用 create 方法则会重新创建一个全新的 RtcEngine 对象

create

public static synchronized RtcEngine com.ss.video.rtc.engine.RtcEngine.create(
    Context context,
    String appId,
    IRtcEngineEventHandler handler,
    EGLContext eglContext)

创建引擎对象
此方法应该作为正常 SDK 流程中的第一步操作，通过创建一个引擎实例，来使用 SDK 的其他能力

传入参数

返回值

• RtcEngine 创建成功。返回一个可用的 RtcEngineImpl 实例
• null so 加载失败，创建失败。返回 null

注意

• 调用者应注意保持 handler 的生命周期必须大于 RtcEngine 的生命周期，即 handler 必须在调用 create 之前创建，在调用 destroy 之后销毁
• 连续多次调用 create 方法将不会创建新的 RtcEngine，只有第一次调用 会创建一个新的实例，并设置相关的 handler，后续的调用将不会更新 handler，而是直接返回第一次创建的 RtcEngine 对象
• 在调用 destroy 之后会销毁 RtcEngine，再次调用 create 方法则会重新创建一个全新的 RtcEngine 对象

create

public static synchronized RtcEngine com.ss.video.rtc.engine.RtcEngine.create(
    Context context,
    String appId,
    IRtcEngineEventHandler handler,
    javax.microedition.khronos.egl.EGLContext eglContext)

创建引擎对象
此方法应该作为正常 SDK 流程中的第一步操作，通过创建一个引擎实例，来使用 SDK 的其他能力

传入参数

返回值

• RtcEngine 创建成功。返回一个可用的 RtcEngineImpl 实例
• null so 加载失败，创建失败。返回 null

注意

• 调用者应注意保持 handler 的生命周期必须大于 RtcEngine 的生命周期，即 handler 必须在调用 create 之前创建，在调用 destroy 之后销毁
• 连续多次调用 create 方法将不会创建新的 RtcEngine，只有第一次调用 会创建一个新的实例，并设置相关的 handler，后续的调用将不会更新 handler，而是直接返回第一次创建的 RtcEngine 对象
• 在调用 destroy 之后会销毁 RtcEngine，再次调用 create 方法则会重新创建一个全新的 RtcEngine 对象

destroy

public static synchronized void com.ss.video.rtc.engine.RtcEngine.destroy()

销毁引擎 销毁由 create 所创建引擎实例，并释放所有相关资源

注意

• 请确保一定是在所有业务场景的最后阶段才调用该方法
• 该方法在调用之后，会销毁所有SDK相关的内存，并且停止与媒体服务器的任何交互
• 该方法不会销毁任何配置，在上一次 create调用之后对SDK进行的任何配置， 在下一次有效执行 create 时依然生效
• 本方法为阻塞调用，会阻塞当前线程直到SDK彻底完成退出逻辑，因而需要注意不要在回调线程中直接调用 本方法，也需要注意不要在回调方法中等待主线程的执行，而同时在主线程调用本方法，从而造成死锁

getSdkVersion

public static String com.ss.video.rtc.engine.RtcEngine.getSdkVersion()

获取 SDK 当前的版本号。

返回值

SDK 当前的版本号。

getErrorDescription

public static String com.ss.video.rtc.engine.RtcEngine.getErrorDescription(
    int code)

获取SDK内各种错误码、警告码的描述文字

传入参数

返回值

String 描述文字

setRtcEngineEventHandler

public static void com.ss.video.rtc.engine.RtcEngine.setRtcEngineEventHandler(
    IRtcEngineEventHandler engineEventHandler)

设置引擎事件回调的接收类，必须继承自 IRtcEngineEventHandler 。

传入参数

注意

• 调用方需要自行实现一个继承自 IRtcEngineEventHandler 的类，并重载其中需要关注的事件。
• 该回调为异步回调
• 所有的事件回调均会在独立的回调线程内触发，请接收回调事件时注意所有与线程运行环境有关的操作，如需要在 UI 线程内执行的操作等， 请勿直接在回调函数的实现中直接进行操作。

enablePerformanceCollect

public static void com.ss.video.rtc.engine.RtcEngine.enablePerformanceCollect(
    boolean enable)

由外部控制是否开启性能采集，默认关闭。

传入参数

注意

• 此接口和 joinChannel 信令的 ACK 均可以控制 SDK 的性能采集，需要制定优先级：
• 调用此接口设置时，以此接口设置为准。
• 当没有调用此接口设置时，以 joinChannel 信令的 ACK 为准。

feedback

public static int com.ss.video.rtc.engine.RtcEngine.feedback(
    Context context,
    int grade,
    int type,
    String problemDesc)

本次通话质量打分评价。

传入参数

返回值

• 0： 成功。
• <0： 失败。
• -1： 在加入房间之前调用该接口。
• -2： 报字段解析失败。
• -3： 上报字段缺失。
• -4： grade 字段不合法。

注意

• 请在加入房间之后调用该接口，否则可能上报失败，或上报字段缺失。
• 离开房间之后，进程退出之前，接口有效。
• 其中 type 字段可以对 ProblemFeedback 进行或运算实现多选。

joinChannel

public abstract int com.ss.video.rtc.engine.RtcEngine.joinChannel(
    String token,
    String channelName,
    PublisherConfiguration publisherConfiguration,
    String uid)

加入房间。用户调用此方法加入房间，在一个房间内的用户间可以相互通话。
用户调用 create 方法创建 RTC 引擎后，需调用此方法加入房间实现同其他用户进行音视频通话。如果用户调用此方法加入房间，则后续重复调用此方法均会失败，用户必须调用 leaveChannel 退出当前房间后，才能加入下一个房间。
用户调用此方法加入房间成功后，会收到 onJoinChannelSuccess 回调通知。

传入参数

返回值

方法调用结果。
+ 0: 成功
+ -1: channelName 为空，失败
+ -2: uid 为空，失败
+ -3: Engine 创建失败
+ -4: joinChannel(@link #joinChannel) 重复调用，失败

注意

• 使用不同 App ID 的 App 是不能互通的。
• 请务必保证生成 Token 使用的 App ID 和创建引擎时使用的 App ID 相同，否则会导致加入房间失败。
• 用户加入房间成功后，在本端网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本端会收到 onRejoinChannelSuccess 回调通知。
• 房间模式（房间模式参考 setChannelProfile ）为通话模式下的用户或直播、游戏、云游戏模式下用户角色（用户角色参考 setClientRole ）为主播、观众的用户加入房间成功后，远端用户会收到 onJoinChannelSuccess 回调通知。
• 同一个 App ID 的同一个房间内，每个用户的用户ID 必须是唯一的。如果两个用户的用户ID 相同，则后加入房间的用户会将先加入房间的用户踢出房间，并且先加入房间的用户会收到 onError 回调通知，错误类型为重复登录 BRERR_DUPLICATE_LOGIN 。

leaveChannel

public abstract int com.ss.video.rtc.engine.RtcEngine.leaveChannel()

离开房间。
用户调用此方法离开房间，结束通话过程，释放所有通话相关的资源。
调用 joinChannel 方法加入房间后，在通话结束时必须调用此方法结束通话，否则无法开始下一次通话。无论当前是否在房间中，都可以调用此方法。重复调用此方法不会有负面影响。
此方法是异步操作，调用返回时并没有真正退出房间。真正退出房间后，本端会收到 onLeaveChannel 回调通知。

返回值

方法调用结果。
+ 0: 方法调用成功
+ <0: 方法调用失败

注意

• 通信模式下的用户和其他房间模式下的主播、 观众角色的用户离开房间后，远端用户会收到 onUserOffline 回调通知。
• 如果调用 leaveChannel 后立即调用销毁引擎，SDK 将无法触发 onLeaveChannel 回调。

enableLocalVideo

public abstract int com.ss.video.rtc.engine.RtcEngine.enableLocalVideo(
    boolean enabled)

该方法开启或关闭本地视频采集。默认为开启状态。
调用该方法后，房间中的其他用户会收到 onUserEnableLocalVideo 的回调。

传入参数

返回值

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

注意

• 关闭本地视频采集后，不会编码发送视频数据。
• 只有同时调用 enableLocalVideo(true) 与 startPreview 才会打开视频采集设备。
• 只要调用 enableLocalVideo(false) 或 stopPreview 的任意一个就会关闭视频采集设备。
• 该方法在 joinChannel 前可以调用。
• 该方法设置的是内部引擎为启用或禁用状态，在 leaveChannel 后仍然有效。

enableLocalAudio

public abstract int com.ss.video.rtc.engine.RtcEngine.enableLocalAudio(
    boolean enabled)

开启关闭本地音频。
调用该方法后，房间中的其他用户会收到 onUserEnableLocalAudio 的回调。

传入参数

返回值

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

注意

• 关闭本地音频采集后，依然会编码发送静音包，因此依然会有少量 CPU 和网络带宽开销。
• 该方法在 joinChannel 前可以调用。
• 该方法设置的是内部引擎为启用或禁用状态，在 leaveChannel 后仍然有效。

startPreview

public abstract int com.ss.video.rtc.engine.RtcEngine.startPreview()

开启视频预览，视频预览默认为关闭状态。

返回值

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

注意

• 只有同时调用 enableLocalVideo(true) 与 startPreview 才会打开视频采集设备。
• 只要调用 enableLocalVideo(false) 或 stopPreview 的任意一个就会关闭视频采集设备。
• 该方法在 joinChannel 前可以调用。
• 该方法设置的视频预览状态，在 leaveChannel 后仍然有效。
• 调用 leaveChannel 退出频道，并不会关闭视频预览。如需关闭视频预览，请调用 stopPreview

stopPreview

public abstract int com.ss.video.rtc.engine.RtcEngine.stopPreview()

关闭视频预览，视频预览默认为关闭状态。

返回值

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

注意

• 只有同时调用 enableLocalVideo(true) 与 startPreview 才会打开视频采集设备。
• 只要调用 enableLocalVideo(false) 或 stopPreview 的任意一个就会关闭视频采集设备。
• 该方法在 joinChannel 前可以调用。
• 该方法设置的视频预览状态，在 leaveChannel 后仍然有效。

setupLocalVideo

public abstract int com.ss.video.rtc.engine.RtcEngine.setupLocalVideo(
    VideoCanvas local)

设置本地视频显示属性

传入参数

返回值

• 0: 方法调用成功
• -1: VideoCanvas 为空

注意

该方法设置本地视频显示信息。应用程序通过调用此接口绑定本地视频流的显示视窗 (view)，并设置视频显示模式。 在应用程序开发中，通常在 APP 收到 onFirstLocalVideoFrame 事件后调用该方法进行本地视频设置，然后再加入房间。 退出房间后，绑定仍然有效，如果需要解除绑定，可以指定空 View（NULL）调用 setupLocalVideo。

setupLocalVideoRender

public abstract int com.ss.video.rtc.engine.RtcEngine.setupLocalVideoRender(
    IVideoSink videoSink,
    String uid)

设置本地视频外部渲染

传入参数

返回值

• 0: 方法调用成功
• -1: 方法调用失败

注意

该方法设置本地视频外部渲染。应用程序通过调用此接口绑定本地视频流的数据源回调。 在应用程序开发中，通常在 APP 收到 onFirstLocalVideoFrame 事件后调用该方法进行本地视频设置，然后再加入房间。 退出房间后，会收到 onStop 和 onDispose，如果需要手动提前 Dispose，需要设置 setupLocalVideoRender为 null，清除设置 。

setupLocalVideoRender

public abstract int com.ss.video.rtc.engine.RtcEngine.setupLocalVideoRender(
    IVideoSink videoSink,
    String uid,
    boolean isInitialized)

设置本地视频外部渲染

传入参数

返回值

• 0: 方法调用成功
• -1: 方法调用失败

注意

该方法设置本地视频外部渲染。应用程序通过调用此接口绑定本地视频流的数据源回调。 在应用程序开发中，通常在 APP 收到 onFirstLocalVideoFrame 事件后调用该方法进行本地视频设置，然后再加入房间。 退出房间后，会收到 onStop 和 onDispose，如果需要手动提前 Dispose，需要设置 setupLocalVideoRender为 null，清除设置 。

setupLocalScreenRender

public abstract int com.ss.video.rtc.engine.RtcEngine.setupLocalScreenRender(
    IVideoSink videoSink,
    String uid)

设置本地屏幕视频的外部渲染

传入参数

返回值

• 0: 方法调用成功
• -1: videoSink 为空
• -2: uid 为空

注意

该方法设置本地屏幕视频外部渲染。应用通过调用此接口绑定本地视频流的数据源回调。 在应用开发中，通常在应用收到 onFirstLocalScreenFrame 事件后调用该方法进行本地视频设置。 退出房间后，需要设置 setupLocalScreenRender 为 null，清除设置 。

setupRemoteVideo

public abstract int com.ss.video.rtc.engine.RtcEngine.setupRemoteVideo(
    VideoCanvas videoCanvas)

设置远端视频视图

传入参数

返回值

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

setupRemoteVideoRender

public abstract int com.ss.video.rtc.engine.RtcEngine.setupRemoteVideoRender(
    IVideoSink videoSink,
    String roomid,
    String uid)

设置远端视频的外部渲染

传入参数

返回值

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

注意

该方法设置远端视频外部渲染。应用程序通过调用此接口绑定远端视频流的数据源回调。 在应用程序开发中，通常在 APP 收到 onFirstRemoteVideoFrame 事件后调用该方法进行远端视频设置，然后再加入房间。 退出房间后，会收到 onStop 和 onDispose，如果需要手动提前 Dispose，需要设置 setupRemoteVideoRender 为 null，清除设置。

setupRemoteVideoRender

public abstract int com.ss.video.rtc.engine.RtcEngine.setupRemoteVideoRender(
    IVideoSink videoSink,
    String uid)

设置远端视频的外部渲染

传入参数

返回值

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

注意

该方法设置远端视频外部渲染。应用程序通过调用此接口绑定远端视频流的数据源回调。 在应用程序开发中，通常在 APP 收到 onFirstRemoteVideoFrame 事件后调用该方法进行远端视频设置，然后再加入房间。 退出房间后，会收到 onStop 和 onDispose，如果需要手动提前 Dispose，需要设置 setupRemoteVideoRender 为 null，清除设置。

setupRemoteVideoRender

public abstract int com.ss.video.rtc.engine.RtcEngine.setupRemoteVideoRender(
    IVideoSink videoSink,
    String roomid,
    String uid,
    boolean isInitialized)

设置远端视频的外部渲染

传入参数

返回值

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

注意

该方法设置远端视频外部渲染。应用程序通过调用此接口绑定远端视频流的数据源回调。 在应用程序开发中，通常在 APP 收到 onFirstRemoteVideoFrame 事件后调用该方法进行远端视频设置，然后再加入房间。 退出房间后，会收到 onStop 和 onDispose，如果需要手动提前 Dispose，需要设置 setupRemoteVideoRender 为 null，清除设置。

setupRemoteVideoRender

public abstract int com.ss.video.rtc.engine.RtcEngine.setupRemoteVideoRender(
    IVideoSink videoSink,
    String uid,
    boolean isInitialized)

设置远端视频的外部渲染

传入参数

返回值

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

注意

该方法设置远端视频外部渲染。应用程序通过调用此接口绑定远端视频流的数据源回调。 在应用程序开发中，通常在 APP 收到 onFirstRemoteVideoFrame 事件后调用该方法进行远端视频设置，然后再加入房间。 退出房间后，会收到 onStop 和 onDispose，如果需要手动提前 Dispose，需要设置 setupRemoteVideoRender 为 null，清除设置。。

setupRemoteScreenRender

public abstract int com.ss.video.rtc.engine.RtcEngine.setupRemoteScreenRender(
    IVideoSink videoSink,
    String roomid,
    String uid)

设置远端屏幕流视频的外部渲染

传入参数

返回值

• 0: 方法调用成功
• -1: videoSink 为空
• -2: uid 为空

注意

该方法设置远端屏幕视频外部渲染。应用通过调用此接口绑定远端视频流的数据源回调。 在应用开发中，通常在应用收到 onFirstRemoteScreenFrame 事件后调用该方法进行远端视频设置。 退出房间后，需要设置 setupRemoteScreenRender 为 null，清除设置 。

setupRemoteScreenRender

public abstract int com.ss.video.rtc.engine.RtcEngine.setupRemoteScreenRender(
    IVideoSink videoSink,
    String uid)

设置远端屏幕流视频的外部渲染

传入参数

返回值

• 0: 方法调用成功
• -1: 方法调用失败

注意

该方法设置远端屏幕视频外部渲染。应用程序通过调用此接口绑定远端视频流的数据源回调。 在应用开发中，通常在应用收到 onFirstRemoteScreenFrame 事件后调用该方法进行远端视频设置。 退出房间后，需要设置 setupRemoteScreenRender 为 null，清除设置 。

setLocalVideoMirrorMode

public abstract int com.ss.video.rtc.engine.RtcEngine.setLocalVideoMirrorMode(
    int mode)

设置本地视频镜像。 该方法设置本地视频镜像，支持动态设置。

传入参数

返回值

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

isLocalVideoMirrorOn

public abstract boolean com.ss.video.rtc.engine.RtcEngine.isLocalVideoMirrorOn()

获取本地视频镜像。

返回值

当前镜像状态
+ true：镜像为打开状态
+ false：镜像为关闭状态

switchCamera

public abstract int com.ss.video.rtc.engine.RtcEngine.switchCamera()

切换前置/后置摄像头

返回值

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

replaceBackground

public abstract int com.ss.video.rtc.engine.RtcEngine.replaceBackground(
    BackgroundMode mode,
    DivideModel divide_model)

视频图像分割，替换背景

传入参数

返回值

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

setEnableSpeakerphone

public abstract int com.ss.video.rtc.engine.RtcEngine.setEnableSpeakerphone(
    boolean enable)

设置音频播放设备为扬声器或者听筒，默认使用扬声器。 音频播放设备发生变化时，会收到 onAudioRouteChanged 回调。

传入参数

返回值

方法调用结果
+ 0: 方法调用成功
+ <0: 方法调用失败

注意

• 该 API 适用于移动设备
• 听筒是手机自带的音频播放设备，一般位于手机顶部，用于打电话。扬声器是手机自带的音频播放设备，一般用于外放。
• 连接有线或者蓝牙音频播放设备时，音频从有线或者蓝牙音频播放设备播放。没有连接有线或者蓝牙音频播放设备时，音频才会从扬声器或者听筒播放。
• 在通话过程中连接有线或者蓝牙音频播放设备时，会自动切换到有线或者蓝牙音频播放设备。
• 在通话过程中移除有线或者蓝牙音频播放设备时，会根据本接口设置，自动切换到听筒或者扬声器。
• 支持在通话前提前设置音频播放设备，也支持在通话过程中切换音频播放设备。

isSpeakerphoneEnabled

public abstract boolean com.ss.video.rtc.engine.RtcEngine.isSpeakerphoneEnabled()

查询扬声器启用状态

返回值

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

enableAudioVolumeIndication

public abstract int com.ss.video.rtc.engine.RtcEngine.enableAudioVolumeIndication(
    int interval,
    int smooth)

启用说话者音量提示。

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

• 该方法启用说话者音量提示。调用该方法后，将以你设置的 internal 为间隔收到 onAudioVolumeIndication 事件回调。

muteLocalAudioStream

public abstract int com.ss.video.rtc.engine.RtcEngine.muteLocalAudioStream(
    boolean muted)

静音本地音频流。 调用该方法后，房间中的其他用户会收到 onUserMuteAudio 的回调。

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

• 本方法只是静音本地流，并未关闭本地音频采集设备。

muteLocalVideoStream

public abstract int com.ss.video.rtc.engine.RtcEngine.muteLocalVideoStream(
    boolean muted)

开启/关闭本地视频发送，调用该方法后，房间中的其他用户会收到 onUserMuteVideo 的回调。

传入参数

返回值

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

muteAllRemoteVideoStreams

public abstract int com.ss.video.rtc.engine.RtcEngine.muteAllRemoteVideoStreams(
    boolean muted)

开启/关闭所有远程视频流

传入参数

返回值

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

setDefaultMuteAllRemoteVideoStreams

public abstract int com.ss.video.rtc.engine.RtcEngine.setDefaultMuteAllRemoteVideoStreams(
    boolean muted)

停止/恢复接受所有新加入房间用户的远端视频流

传入参数

返回值

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

muteAllRemoteAudioStreams

public abstract int com.ss.video.rtc.engine.RtcEngine.muteAllRemoteAudioStreams(
    boolean muted)

静音/取消静音所有音频流

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

本方法只控制本地是否静音远端音频流，并不能控制远端音频设备的采集发送功能

setDefaultMuteAllRemoteAudioStreams

public abstract int com.ss.video.rtc.engine.RtcEngine.setDefaultMuteAllRemoteAudioStreams(
    boolean muted)

设置是否默认静音所有远端音频流

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

• 如果在加入房间前调用此 API，进房后对所有远端用户音频流生效
• 如果在加入房间后调用此 API，则只对在调用 API 之后进房的远端用户的音频流生效
• 对于已静音的远端用户音频流，如果想要取消静音，请参考 muteRemoteAudioStream

muteRemoteAudioStream

public abstract int com.ss.video.rtc.engine.RtcEngine.muteRemoteAudioStream(
    String uid,
    boolean muted)

静音/取消静音指定用户的音频流

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

muteRemoteVideoStream

public abstract int com.ss.video.rtc.engine.RtcEngine.muteRemoteVideoStream(
    String uid,
    boolean muted)

接收/停止接收指定视频流

传入参数

返回值

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

renewToken

public abstract int com.ss.video.rtc.engine.RtcEngine.renewToken(
    String token)

更新 Token。
Token 有一定的有效期，当 Token 过期时，用户需调用此方法更新房间的 Token 信息。
用户调用 joinChannel 方法加入房间时，如果使用了过期的 Token 将导致加入房间失败，并会收到 onError 回调通知，回调错误码为 BRERR_INVALID_TOKEN 。此时需要重新获取 Token ，并调用此方法更新 Token。

传入参数

返回值

方法调用结果。
+ 0: 方法调用成功
+ <0: 方法调用失败

注意

• 如果用户因 Token 过期导致加入房间失败，则调用此方法更新 Token 后 SDK 会自动重新加入房间，而不需要用户自己调用 joinChannel 方法。
• Token过期时，如果已经加入房间成功，则不会受到影响。Token 过期的错误会在下一次使用过期的 Token 加入房间或由于本地网络状况不佳导致断网重连入房间时通知给用户。

setChannelProfile

public abstract int com.ss.video.rtc.engine.RtcEngine.setChannelProfile(
    CHANNEL_PROFILE_TYPE channelProfile)

设置房间模式。
通过设置房间模式，用户可以选择应用 SDK 针对不同房间模式场景的优化策略。
默认的房间模式为通信模式 CHANNEL_PROFILE_COMMUNICATIONCHANNEL_PROFILE_TYPE 。
房间模式必须在调用 joinChannel 加入房间前设置，加入房间后设置不生效。设置用户角色（通过方法 setClientRole ）建议在设置完房间模式后。

传入参数

返回值

方法调用结果。
+ 0: 方法调用成功
+ <0: 方法调用失败

注意

• 为保证音视频质量和实时性，建议相同房间内的用户使用相同的房间模式。

setClientRole

public abstract int com.ss.video.rtc.engine.RtcEngine.setClientRole(
    CLIENT_ROLE_TYPE clientRole)

设置用户角色。
用户可通过设置用户角色，控制：1.是否发布音视频流；2.用户自身是否在房间中隐身。详见用户角色 CLIENT_ROLE_TYPE 。
默认用户角色为主播角色 CLIENT_ROLE_BROADCASTERCLIENT_ROLE_TYPE 。
房间模式（通过调用接口 setChannelProfile 可设置房间模式）为直播模式、游戏模式、云游戏模式时，设置用户角色生效。房间模式为通信模式时不区分用户角色。

传入参数

返回值

方法调用结果。
+ 0: 方法调用成功
+ <0: 方法调用失败

注意

• 在加入房间前，用户可调用此方法设置用户角色。加入房间后，用户也可通过此方法切换用户角色。
• 用户在加入房间成功后调用该方法切换用户角色，调用成功后，远端用户会收到相应的回调通知：1.本地用户角色从静默观众切换至观众或主播时，远端用户会收到 onUserJoined 回调通知；2.本地用户角色从观众或主播切换至静默观众时，远端用户会收到 onUserOffline 回调通知。

startAudioMixing

public abstract int com.ss.video.rtc.engine.RtcEngine.startAudioMixing(
    String file,
    boolean loopback,
    boolean replace,
    int cycle)

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

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 该方法指定本地和麦克风采集的音频流进行混音或替换。替换是指用音频文件替换麦克风采集的音频流。
• 该方法可以选择是否让对方听到本地播放的音频，并指定循环播放的次数。 调用本方法播放音乐文件及混音结束后，应用会收到 onAudioMixingFinished 回调。
• 开始播放音乐文件及混音后，可以调用 stopAudioMixing 方法停止播放音乐文件。
• 该方法混音数据来源外部文件，且支持的文件格式有: mp3，aac，m4a，3gp，wav；而SetAudioPlayoutMixStreamsetAudioPlayoutMixStream 混音的数据来源外部缓存且音频格式为PCM；这两种混音方式可以共存。
• 单个房间只支持一路音乐文件的播放，多次调用该函数后，只有最后一次调用会生效。
• 请在房间内调用该方法。

stopAudioMixing

public abstract int com.ss.video.rtc.engine.RtcEngine.stopAudioMixing()

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

返回值

• 0：成功
• <0：失败

注意

• 调用 startAudioMixing 方法开始播放音乐文件及混音后，调用该方法可以停止播放音乐文件及混音。
• 请在房间内调用该方法。

adjustRecordingSignalVolume

public abstract int com.ss.video.rtc.engine.RtcEngine.adjustRecordingSignalVolume(
    int volume)

调节录音音量。

传入参数

返回值

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

注意

为保证更好的通话质量，建议将 volume 值设为 [0,100]

adjustPlaybackSignalVolume

public abstract int com.ss.video.rtc.engine.RtcEngine.adjustPlaybackSignalVolume(
    int volume)

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

传入参数

返回值

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

注意

• 该方法调节的是本地播放的所有远端用户混音后的音量
• 为保证更好的通话质量，建议将 volume 值设为 [0,100]

pauseAudioMixing

public abstract int com.ss.video.rtc.engine.RtcEngine.pauseAudioMixing()

暂停播放音乐文件

返回值

• 0: 成功
• <0: 失败

注意

• 调用 startAudioMixing 方法开始播放音乐文件及混音后，可以通过调用该方法暂停播放音乐文件。
• 调用该方法暂停播放音乐文件后，可调用 resumeAudioMixing 方法恢复播放。
• 请在房间内调用该方法。

resumeAudioMixing

public abstract int com.ss.video.rtc.engine.RtcEngine.resumeAudioMixing()

恢复播放音乐文件

返回值

• 0: 成功
• <0: 失败

注意

• 调用 pauseAudioMixing 方法暂停播放音乐文件后，可以通过调用该方法恢复播放。
• 请在房间内调用该方法

sendCustomMessage

public abstract void com.ss.video.rtc.engine.RtcEngine.sendCustomMessage(
    String messgaeStr)

给房间内的所有其他用户发送广播消息。

传入参数

注意

• 该函数不适合发送比较频繁的消息，实时性较低。
• 同一房间内的其他用户会收到 onCustomMessage 回调。

sendMessage

public abstract long com.ss.video.rtc.engine.RtcEngine.sendMessage(
    String userId,
    String messageStr)

给房间内指定的用户发送消息, 返回这次发送消息的编号。
调用该函数后会收到一次 onMessageSendResult 回调，告知发送结果。

传入参数

返回值

• >0： 发送成功，返回这次发送消息的编号，从 1 开始递增。
• <0： 失败。
• -1： RTCEngine 实例未创建。
• -2： uid 为空。

注意

• 该函数只能在云游戏模式下使用，设置频道模式参见 setChannelProfile 函数调用。
• 发送消息方必须订阅接受消息方的流才能主动发送第一条消息，之后双方可以互发消息，该函数适合发送比较频繁且实时性要求高的消息。
• 若消息发送成功，则 uid 所指定的用户会收到 onMessageReceived 回调。

adjustAudioMixingVolume

public abstract int com.ss.video.rtc.engine.RtcEngine.adjustAudioMixingVolume(
    int volume)

调节音乐文件的文件音量。为保证更好的音质，建议将 volume 值设为 [0,100]。

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法可同时调节的是本地和远端播放音量。仅调节本端音量可使用 adjustAudioMixingPlayoutVolume ， 仅调节远端音量可使用 adjustAudioMixingPublishVolume。
• 该方法对 adjustAudioMixingPlayoutVolume 和 adjustAudioMixingPublishVolume 的音量调节影响是乘积关系。
• 请在房间内调用该方法。

getAudioMixingDuration

public abstract int com.ss.video.rtc.engine.RtcEngine.getAudioMixingDuration()

获取音乐文件时长

返回值

• >0: 成功, 音乐文件时长，单位为毫秒。
• <0: 失败

注意

请在房间内调用该方法。

getAudioMixingCurrentPosition

public abstract int com.ss.video.rtc.engine.RtcEngine.getAudioMixingCurrentPosition()

获取音乐文件播放进度

返回值

• >0: 成功, 音乐文件播放进度，单位为毫秒。
• <0: 失败

注意

请在房间内调用该方法。

setAudioMixingPosition

public abstract int com.ss.video.rtc.engine.RtcEngine.setAudioMixingPosition(
    int pos)

设置音频文件的播放位置

传入参数

返回值

• 0: 成功
• <0: 失败

注意

该方法可以设置音频文件的播放位置，这样你可以根据实际情况从指定的位置播放音乐文件，无需从头到尾完整播放一个音乐文件。

adjustAudioMixingPlayoutVolume

public abstract int com.ss.video.rtc.engine.RtcEngine.adjustAudioMixingPlayoutVolume(
    int volume)

调节音乐文件的本地播放音量。为保证更好的音质，建议将 volume 值设为 [0,100]。

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法可以调节混音的音乐文件在本地播放的音量大小。如果需要同时调节本地和远端播放音量可使用 adjustAudioMixingVolume 方法。
• 请在房间内调用该方法。

adjustAudioMixingPublishVolume

public abstract int com.ss.video.rtc.engine.RtcEngine.adjustAudioMixingPublishVolume(
    int volume)

调节音乐文件的远端播放音量。为保证更好的音质，建议将 volume 值设为 [0,100]。

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 该方法调节混音的音乐文件在远端播放的音量大小。如果需要同时调节本地和远端播放音量可使用 adjustAudioMixingVolume 方法。
• 请在房间内调用该方法。

getEffectVolume

public abstract int com.ss.video.rtc.engine.RtcEngine.getEffectVolume(
    int soundId)

获取指定音效文件的文件音量

传入参数

返回值

• >0: 成功，文件音量，音量范围为 0~400。
• <0: 失败

注意

请在房间内调用该方法。

setVolumeOfEffect

public abstract int com.ss.video.rtc.engine.RtcEngine.setVolumeOfEffect(
    int soundId,
    int volume)

调节指定音效文件的文件音量。为保证更好的音质，建议将 volume 值设为 [0,100]。

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 该方法调节音效文件在本地和远端播放的音量大小。
• 请在房间内调用该方法。

setEffectsVolume

public abstract int com.ss.video.rtc.engine.RtcEngine.setEffectsVolume(
    int volume)

调节所有音效文件的文件音量。为保证更好的音质，建议将 volume 值设为 [0,100]。

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 该方法调节混音的所有音效文件在本地和远端播放的音量大小。
• 请在房间内调用该方法。

playEffect

public abstract int com.ss.video.rtc.engine.RtcEngine.playEffect(
    int soundId,
    String filePath,
    boolean loopback,
    int cycle,
    int volume)

开始播放指定音效文件。你可以在该方法中设置音效文件的播放次数、音量大小，以及远端用户是否能听到该音效。

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法播放音效结束后，应用会收到 onAudioEffectFinished 回调。
• 可以多次调用该方法，通过传入不同的音效文件的 soundId 和 filePath，以实现同时播放多个音效文件，实现音效叠加。
• 可以通过 stopEffect 方法停止播放指定音效文件。
• 请在房间内调用该方法。

preloadEffect

public abstract int com.ss.video.rtc.engine.RtcEngine.preloadEffect(
    int soundId,
    String filePath)

预加载指定音效文件

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法预加载播放指定音效文件。预加载操作可以在进房间之前完成（所有混音相关接口，如果没有标注请在房间内调用都可在没有进入房间的时候调用）。如果音效文件很长，加载操作可能会耗时较长，建议应用开发者将预加载操作放在子线程进行。
• 该方法只是预加载播放指定音效文件，只有通过 playEffect 才开始播放指定音效文件。
• 该方法预加载指定音效文件可以通过 unloadEffect 来卸载。

unloadEffect

public abstract int com.ss.video.rtc.engine.RtcEngine.unloadEffect(
    int soundId)

卸载指定音效文件

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 该方法卸载指定音效文件。
• 如果调用 stopEffect 方法时音效文件没有被卸载，SDK会自动调用该方法卸载音效文件。

stopEffect

public abstract int com.ss.video.rtc.engine.RtcEngine.stopEffect(
    int soundId)

停止播放指定音效文件

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 该方法停止播放指定音效文件。
• 该方法内部会主动调用 unloadEffect 来卸载指定音效文。

pauseEffect

public abstract int com.ss.video.rtc.engine.RtcEngine.pauseEffect(
    int soundId)

暂停播放指定音效文件

传入参数

返回值

• 0: 成功
• <0: 失败

注意

调用该方法暂停播放指定音效文件，可以调用 resumeEffect 方法恢复播放。

resumeEffect

public abstract int com.ss.video.rtc.engine.RtcEngine.resumeEffect(
    int soundId)

恢复播放指定音效文件

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用 pauseEffect 方法暂停播放指定音效文件后， 可以通过该方法恢复播放。
• 调用 pauseAllEffects 方法暂停所有音效文件的播放后，也可以通过该方法恢复单个音效文件播放。

stopAllEffects

public abstract int com.ss.video.rtc.engine.RtcEngine.stopAllEffects()

停止所有音效文件的播放

返回值

• 0: 成功
• <0: 失败

注意

该方法停止所有音效文件的播放。

unloadAllEffects

public abstract int com.ss.video.rtc.engine.RtcEngine.unloadAllEffects()

卸载所有音效文件

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法卸载所有音效文件。如果引擎被销毁时有音效文件没有被卸载，SDK会自动调用该方法卸载所有音效文件。
• 调用 leaveChannel 离开房间后，不会自动调用该方法卸载所有音效文件。如果需要在离开房间后卸载所有音效文件，需要应用主动调用该方法。

pauseAllEffects

public abstract int com.ss.video.rtc.engine.RtcEngine.pauseAllEffects()

暂停所有音效文件的播放

返回值

• 0: 成功
• <0: 失败

注意

该方法暂停所有音效文件的播放，可调用 resumeAllEffects 方法恢复播放。

resumeAllEffects

public abstract int com.ss.video.rtc.engine.RtcEngine.resumeAllEffects()

恢复所有音效文件的播放

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法恢复所有音效文件的播放。在调用 pauseAllEffects 暂停所有音效文件的播放后，可以调用该方法可恢复所有音效文件的播放。
• 调用 pauseEffect 方法暂停单个指定音效文件的播放后，也可以调用该方法恢复播放，但是效率太低，不推荐这么使用。

setRecordingAudioFrameParameters

public abstract boolean com.ss.video.rtc.engine.RtcEngine.setRecordingAudioFrameParameters(
    int sampleRate,
    int channels)

设置本地麦克风录制的音频数据回调参数

传入参数

返回值

方法调用结果
+ true：方法调用成功
+ false：方法调用失败

注意

使用本方法设置参数，并使用registerAudioFrameObserver注册数据观察者，之后可以在IAudioFrameObserver的 onRecordAudioFrame收到数据

setPlaybackAudioFrameParameters

public abstract boolean com.ss.video.rtc.engine.RtcEngine.setPlaybackAudioFrameParameters(
    int sampleRate,
    int channels)

设置远端所有用户音频数据混音后的音频数据回调参数

传入参数

返回值

方法调用结果
+ true：方法调用成功
+ false：方法调用失败

注意

使用本方法设置参数，并使用registerAudioFrameObserver注册数据观察者，之后可以在IAudioFrameObserver的 onPlaybackAudioFrame收到数据

setMixedAudioFrameParameters

public abstract boolean com.ss.video.rtc.engine.RtcEngine.setMixedAudioFrameParameters(
    int sampleRate,
    int channels)

设置本地麦克风录制音频数据和远端所有用户音频数据混音后的音频数据回调参数

传入参数

返回值

方法调用结果
+ true：方法调用成功
+ false：方法调用失败

注意

使用本方法设置参数，并使用registerAudioFrameObserver注册数据观察者，之后可以在IAudioFrameObserver的 onMixedAudioFrame收到数据

registerAudioFrameObserver

public abstract int com.ss.video.rtc.engine.RtcEngine.registerAudioFrameObserver(
    IAudioFrameObserver observer)

注册音频数据回调观察者

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

本方法需要与下面3个方法配合使用：setRecordingAudioFrameParameters、 setPlaybackAudioFrameParameters、 setMixedAudioFrameParameters

setExternalVideoSource

public abstract void com.ss.video.rtc.engine.RtcEngine.setExternalVideoSource(
    boolean enable,
    boolean useTexture,
    boolean push)

配置外部视频源。 不支持频道内动态切换视频源。如果想切换成视频源，须先退出频道，再重新加入频道。

传入参数

setExternalVideoSource

public abstract void com.ss.video.rtc.engine.RtcEngine.setExternalVideoSource(
    boolean enable,
    boolean useTexture,
    boolean push,
    boolean needRender)

配置外部视频源。 不支持频道内动态切换视频源。如果想切换成视频源，须先退出频道，再重新加入频道。

传入参数

pushExternalVideoFrame

public abstract boolean com.ss.video.rtc.engine.RtcEngine.pushExternalVideoFrame(
    RtcVideoFrame frame)

推送外部视频帧。

传入参数

返回值

• true: 成功
• false: 失败

注意

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

pushExternalVideoFrame

public abstract boolean com.ss.video.rtc.engine.RtcEngine.pushExternalVideoFrame(
    RtcVideoFrame frame,
    boolean isDirectEncode)

推送外部视频帧。

传入参数

返回值

• true: 成功
• false: 失败

注意

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

enableLiveTranscoding

public abstract void com.ss.video.rtc.engine.RtcEngine.enableLiveTranscoding(
    LiveTranscoding liveTranscode)

开启直播推流转码功能。
此方法用于开启直播推流转码功能，并设置旁路推流的视频视图布局及音频属性等。
直播推流转码功能开启时，会根据设置的视频视图布局和音频属性进行合流转码转成 rtmp 流并推送到设置的 CDN 。
直播推流转码功能启动成功或失败时、推流过程中发生错误时，SDK 通过 onStreamPublished 回调事件通知用户对应的状态事件。

传入参数

注意

• 只有房间模式为直播模式，且用户角色为主播的用户才能调用此方法。

disableLiveTranscoding

public abstract void com.ss.video.rtc.engine.RtcEngine.disableLiveTranscoding()

关闭直播推流转码功能。

setVideoCompositingLayout

public abstract void com.ss.video.rtc.engine.RtcEngine.setVideoCompositingLayout(
    LiveTranscoding.Layout layout)

设置视频流合流布局。
此方法用于在直播推流转码功能开启时，更新旁路推流的视频合流布局属性。调用此方法前，用户需通过调用 enableLiveTranscoding 方法开启直播推流转码功能。如果未开启直播推流转码功能，则调用此方法不生效。

传入参数

setVideoProfiles

public abstract int com.ss.video.rtc.engine.RtcEngine.setVideoProfiles(
    VideoStreamDescription[] videoStreamDescriptions)

设置发布的视频流属性

传入参数

返回值

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

setVideoProfiles

public abstract int com.ss.video.rtc.engine.RtcEngine.setVideoProfiles(
    VideoStreamDescription[] videoStreamDescriptions,
    VideoEncoderConfiguration.ORIENTATION_MODE orientationMode)

设置发布的视频流属性和视频旋转角度

传入参数

返回值

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

setupRemoteScreen

public abstract void com.ss.video.rtc.engine.RtcEngine.setupRemoteScreen(
    VideoCanvas videoCanvas)

设置共享屏幕远端视频视图。

传入参数

注意

在应用开发中，通常在应用收到 onFirstRemoteScreenFrame 事件后调用该方法进行远端视频设置。

enableAutoSubscribe

public abstract void com.ss.video.rtc.engine.RtcEngine.enableAutoSubscribe(
    boolean enable)

开启/关闭自动订阅功能。
用户调用此方法设置房间中是否开启自动订阅功能。SDK 默认开启自动订阅功能。
如需关闭自动订阅功能，建议在调用 joinChannel 方法加入房间前设置完成。

传入参数

注意

• SDK 提供两种订阅模式：1.自动订阅模式，开启自动订阅功能时，SDK 自动帮助用户订阅房间中所有其他用户发布的音视频流；2.手动订阅模式，关闭自动订阅功能时，SDK不会自动订阅房间内的音视频流，只通过 onStreamAdd 和 onStreamRemove 回调通知用户当前所在房间中有哪些音视频流，由用户根据自己的需要调用 subscribeStream 方法手动订阅其他用户发布的音视频流。

subscribeStream

public abstract void com.ss.video.rtc.engine.RtcEngine.subscribeStream(
    String userId,
    SubscribeConfig info)

订阅指定的房间内远端音视频流。
关闭自动订阅功能，使用手动订阅模式时用户调用此方法按需订阅房间中的音视频流。
此方法仅在关闭自动订阅功能时生效。用户需在加入房间前调用 enableAutoSubscribe 方法关闭自动订阅功能以使用手动订阅模式。
订阅流失败时，SDK 会按失败原因回调 onError 通知用户，具体错误可参考错误码 RtcErrorCode 描述。

传入参数

注意

• 此方法仅支持订阅当前房间中的远端音视频流。如果指定的流在当前房间内不曾存在，则 SDK 不会订阅。
• 用户调用 joinChannel 方法加入房间后：1.当房间内有新的音视频流发布时，本端会收到 onStreamAdd 回调通知；2.当房间内音视频流停止发布时，本端会收到 onStreamRemove 回调通知。通过这两个回调用户可以获得当前房间中的音视频流信息，并在需要时调用此方法订阅该音视频流。

unSubscribe

public abstract void com.ss.video.rtc.engine.RtcEngine.unSubscribe(
    String userId,
    boolean isScreen)

停止订阅指定的房间内远端音视频流。
关闭自动订阅功能，使用手动订阅模式时用户调用此方法停止订阅已订阅的音视频流。
此方法仅在开启手动订阅功能时生效，用户需在加入房间前调用 enableAutoSubscribe 方法关闭自动订阅功能以使用手动订阅模式。

传入参数

注意

• 不管是否订阅了指定的远端音视频流，都可以调用此方法停止订阅。停止订阅的 streamId 无效或未订阅时，SDK不会做任何处理，没有负面影响。

setExternalAudioDevice

public abstract boolean com.ss.video.rtc.engine.RtcEngine.setExternalAudioDevice(
    boolean enable,
    int sampleRate,
    int recordChannelNum,
    int playoutChannelNum)

设置是否启用外部音频采集渲染

传入参数

返回值

设置是否成功
+ true: 成功
+ false: 失败

注意

• 该方法应该在 joinChannel 前使用。
• 启用自定义音频采集渲染后，使用 pushExternalAudioFrame 推送音频数据。
• 启用自定义音频采集渲染后，使用 pullExternalAudioFrame 拉取音频数据。

setAudioDeviceEventHandler

public abstract boolean com.ss.video.rtc.engine.RtcEngine.setAudioDeviceEventHandler(
    IRtcEngineAudioDeviceEventHandler handler)

启动音频外部源采集渲染时，添加音频外部设备事件监控

传入参数

返回值

方法调用结果
+ true：方法调用成功
+ false：方法调用失败

pushExternalAudioFrame

public abstract boolean com.ss.video.rtc.engine.RtcEngine.pushExternalAudioFrame(
    byte[] audioFrame,
    int frameNum)

推送外部音频数据。使用 setExternalAudioDevice 启用自定义音频采集渲染后，可以使用本方法推送外部音频数据。

传入参数

返回值

方法调用结果
+ true:方法调用成功
+ false：方法调用失败

注意

• 必须是pcm数据，推送间隔是10ms，音频采样格式为s16。
• 该函数运行在用户调用线程内，是一个同步函数

pullExternalAudioFrame

public abstract boolean com.ss.video.rtc.engine.RtcEngine.pullExternalAudioFrame(
    byte[] audioFrame,
    int frameNum)

拉取远端音频数据。使用 setExternalAudioDevice 启用自定义音频采集渲染后，可以使用本方法拉取远端音频数据。

传入参数

返回值

方法调用结果
+ true:方法调用成功
+ false：方法调用失败

注意

• 必须是pcm数据，拉取间隔是10ms，音频采样格式为s16。
• 该函数运行在用户调用线程内，是一个同步函数

setupLocalScreen

public abstract int com.ss.video.rtc.engine.RtcEngine.setupLocalScreen(
    VideoCanvas videoCanvas)

设置共享屏幕渲染本地视图

传入参数

返回值

• 0: 设置成功
• -1: 设置失败

注意

在应用开发中，通常在应用收到 onFirstLocalScreenFrame 事件后调用该方法进行本地视频设置。

publishScreen

public abstract int com.ss.video.rtc.engine.RtcEngine.publishScreen()

发布本地屏幕共享流。

返回值

0 :发布成功 -1 :发布失败

注意

1. 直播、游戏、云游戏房间模式下，此方法仅适用于角色为主播的用户。应用可以通过调用 setClientRole 方法设置用户角色。
2. 调用此方法发布本端屏幕共享流后，用户还需要通过设置定时任务周期性调用 pushScreenFrame 方法，将需要发送的屏幕数据推送给 SDK。
3. 调用该接口后远端能收到 onFirstRemoteScreenFrame 和 onStreamAdd 事件。
4. 调用该接口后本地能收到 onFirstLocalScreenFrame 事件。

unpublishScreen

public abstract int com.ss.video.rtc.engine.RtcEngine.unpublishScreen()

停止发布本地屏幕共享流。

返回值

0 :发布成功 -1 :发布失败

注意

调用该接口后远端会收到 onStreamRemove 事件

pushScreenFrame

public abstract boolean com.ss.video.rtc.engine.RtcEngine.pushScreenFrame(
    RtcVideoFrame videoFrame)

发布共享屏幕视频帧

传入参数

返回值

true :发布成功 false :发布失败

setOnDestroyCompletedCallback

public abstract void com.ss.video.rtc.engine.RtcEngine.setOnDestroyCompletedCallback(
    Runnable callback)

设置引擎销毁后通知 App 的回调函数。

传入参数

setAudioPlayoutMixStream

public abstract void com.ss.video.rtc.engine.RtcEngine.setAudioPlayoutMixStream(
    boolean enable,
    int sampleRate,
    int channelNum)

启动/停止外部音频流混音， 并设置混音数据格式

传入参数

注意

• 调用该方法设置外部音频混音的PCM格式，即 pushAudioMixingStreamData 的 audioFrame 的音频数据格式。
• 调用该方法混音的数据来源外部缓存，且音频格式为PCM； startAudioMixing 方法混音数据来源外部文件，且支持的文件格式有: mp3，aac，m4a，3gp，wav。这两种混音方式可以共存。
• enable 为 false 时，停止外部音频流混音。 或者引擎释放时，SDK内部会停止混音。
• 该方法启动的外部音频流混音不支持音量调节，暂停，暂停恢复操作。

getAudioMixingStreamCachedFrameNum

public abstract int com.ss.video.rtc.engine.RtcEngine.getAudioMixingStreamCachedFrameNum()

获取SDK当前缓冲数据

返回值

• >0: 成功，缓冲的音频采样点个数。
• 0: 失败

注意

调用该方法可以实时获取缓存数据量，并以此数据为基准调整数据推送节奏来避免内存溢出

pushAudioMixingStreamData

public abstract boolean com.ss.video.rtc.engine.RtcEngine.pushAudioMixingStreamData(
    byte[] audioFrame,
    int frameNum)

向SDK推送混音的音频数据

传入参数

返回值

• true: 成功
• false: 失败

注意

• 调用该方法前，必须通过 setAudioPlayoutMixStream 方法设置 audioFrame 的数据格式。
• 调用该方法前，先通过 getAudioMixingStreamCachedFrameNum 获取缓存的数据量，并调整推送数据的节奏以避免内部缓存溢出导致推送失败。
• 使用参考建议：首次推送数据，请在应用侧先缓存一定数据（如 200 毫秒）， 然后一次性推送过去；此后的推送操作定时 10 毫秒一次，并且每次的音频数据量为 10 毫秒数据量。

AdjustRemoteAudioVolume

public abstract void com.ss.video.rtc.engine.RtcEngine.AdjustRemoteAudioVolume(
    String uid,
    int volume)

调节远端用户音量，默认为100

传入参数

setPublishFallbackOption

public abstract int com.ss.video.rtc.engine.RtcEngine.setPublishFallbackOption(
    int option)

设置发布的音视频流回退选项。

传入参数

返回值

• 0： 成功。
• <0： 失败。

注意

• 在网络情况不理想、设备性能不足时，实时音视频的质量会下降。通过这个接口来设置网络情况不佳或性能不足时只发送小流，以保证通话质量。
• 这个方法只在设置了发送多个流的情况下有效。
• 必须在进房前设置，进房后设置或更改设置无效。
• 设置回退选项后，本端发布的音视频流发生回退或从回退中恢复时，对端会收到 onRemoteStreamSwitch 回调通知。

setRemoteSubscribeFallbackOption

public abstract int com.ss.video.rtc.engine.RtcEngine.setRemoteSubscribeFallbackOption(
    SubscribeFallbackOptions option)

设置订阅的音视频流回退选项。

传入参数

返回值

• 0： 成功。
• <0： 失败。

注意

• 在网络情况不理想、设备性能不足时，实时音视频的质量会下降。通过这个接口来设置网络情况不佳或性能不足时只订阅小流或音频流，以保证通话质量。
• 必须在进房前设置，进房后设置或更改设置无效。
• 设置回退选项后，本端订阅的音视频流发生回退或从回退中恢复时，会收到 onRemoteStreamSwitch 回调通知。
• 设置回退选项后，本端订阅的视频流因为回退分辨率发生变化时，会收到 onVideoSizeChanged 回调通知。

setRemoteUserPriority

public abstract int com.ss.video.rtc.engine.RtcEngine.setRemoteUserPriority(
    String uid,
    RemoteUserPriority priority)

设置用户优先级。

传入参数

返回值

• 0： 成功。
• <0： 失败。

注意

• 该方法与 setRemoteSubscribeFallbackOption 搭配使用。
• 如果开启了订阅流回退选项，弱网或性能不足时会优先保证收到的高优先级用户的流的质量。
• 该方法在进房前后都可以使用，可以修改远端用户的优先级。

registerMetadataObserver

public abstract void com.ss.video.rtc.engine.RtcEngine.registerMetadataObserver(
    IMetadataObserver observer)

注册 metadata 观察者，用于接收或发送 metadata，底层通过在视频帧中添加 SEI 数据实现该功能。
注册观察者后，发送的视频帧里面没有 SEI 信息， 会触发 onReadyToSendMetadata 回调。
注册观察者后，接收的视频帧里面有 SEI 信息，会触发接收 onMetadataReceived 回调。

传入参数

注意

• 使用视频自定义采集与渲染时，可以直接在视频帧中添加与获取 metadata，不建议使用本接口。
• 本接口支持动态取消注册，将参数设置为 nullptr 取消注册。

setBusinessId

public abstract int com.ss.video.rtc.engine.RtcEngine.setBusinessId(
    String businessId)

设置业务标识参数。
可通过 businessId 区分不同的业务场景（角色/策略等）。businessId 由客户自定义，相当于一个“标签”，可以分担和细化现在 AppId 的逻辑划分的功能。

传入参数

返回值

• 0： 成功。
• <0： 失败。
• -6001： 用户已经在房间中。
• -6002： 输入非法，合法字符包括所有小写字母、大写字母和数字，除此外还包括四个独立字符分别是：英文句号，短横线，下划线和 @ 。

注意

• 需要在调用 joinChannel 之前调用，joinChannel 之后调用该方法无效。

SetAudioPerfProfile

public abstract void com.ss.video.rtc.engine.RtcEngine.SetAudioPerfProfile(
    AudioPerfProfile profile)

设置音频处理复杂度。对于希望性能占用较低，可设置较低的音频处理复杂度，如果更在意通话质量，可选择设置更高的音频处理复杂度。 加入房间时，会携带本接口传入的机型等级，然后从服务端拉起相应音频配置。如果传入的是 auto，服务端会查询数据库，获得机型等级，再下发配置。 不同复杂度会开关AEC、ANS、AGC算法，调整播放sample rate等, 进行性能和质量的控制。

传入参数

注意

• 需要在进房之前调用。
• 本次进房时下发的配置，需要下次进房发布才会应用。
• 支持自定义配置，详细操作方式请联系技术支持人员。

setEncryptInfo

public abstract void com.ss.video.rtc.engine.RtcEngine.setEncryptInfo(
    int aesType,
    String key)

设置AES加密算法和加密密钥
有四种内置的加密算法，为 AES-128-CBC，AES-256-CBC，AES-128-ECB，AES-256-ECB

传入参数

注意

• 该方法与 setCustomizeEncryptHandler 为互斥关系, 即按照调用顺序，最后一个调用的方法为最终生效的版本。
• 该方法必须在调用 joinChannel 之前调用，可重复调用，以最后调用的参数作为生效参数
• AES加密算法限制，超过36位的key会被截断，仅取前36位

setCustomizeEncryptHandler

public abstract void com.ss.video.rtc.engine.RtcEngine.setCustomizeEncryptHandler(
    ByteRtcEngineEncryptHandler handler)

设置自定义加密方法 自定义加密方法需要实现对应的加密/解密方法

传入参数

注意

• 该方法与 setEncryptInfo 为互斥关系，即按照调用顺序，最后一个调用的方法为最终生效的版本
• 该方法必须在调用 joinChannel 之前调用，可重复调用，以最后调用的参数作为生效参数
• 无论加密或者解密，其对原始数据的长度修改，需要控制在90%-120%之间，即如果输入数据为100字节，则处理完成后的数据必须在 90至120自己之间，如果加密或解密结果超出该长度限制，则该音视频帧会被丢弃
• 数据加密/解密为串行执行，因而视实现方式不同，可能会影响到最终渲染效率，是否使用该方法，需要由使用方谨慎评估

checkVideoEffectLicense

public abstract int com.ss.video.rtc.engine.RtcEngine.checkVideoEffectLicense(
    Context context,
    String licenseFile)

视频特效许可证检查

传入参数

返回值

0: 许可证验证成功 !0: 许可证验证验证失败

注意

调用enableVideoEffect开始使用视频特效前，需要先调用这个方法进行许可证验证

setVideoEffectAlgoModelPath

public abstract void com.ss.video.rtc.engine.RtcEngine.setVideoEffectAlgoModelPath(
    String modelPath)

设置视频特效算法模型路径

传入参数

enableVideoEffect

public abstract int com.ss.video.rtc.engine.RtcEngine.enableVideoEffect(
    boolean enable)

开启关闭视频特效

传入参数

返回值

0: 成功 !0: 失败。

注意

在调用checkVideoEffectLicense和setVideoEffectAlgoModelPath后调用此方法。

setVideoEffectPath

public abstract void com.ss.video.rtc.engine.RtcEngine.setVideoEffectPath(
    List<String> effectPaths)

设置视频Effect资源路径，可以一次设置多种资源

传入参数

addVideoEffectPath

public abstract void com.ss.video.rtc.engine.RtcEngine.addVideoEffectPath(
    List<String> effectPaths)

增加特效包，支持同时增加多个特效包

传入参数

removeVideoEffectPath

public abstract void com.ss.video.rtc.engine.RtcEngine.removeVideoEffectPath(
    List<String> effectPaths)

移除特效包，支持同时移除多个特效包

传入参数

updateVideoEffect

public abstract void com.ss.video.rtc.engine.RtcEngine.updateVideoEffect(
    String effectPath,
    String key,
    float value)

设置特效强度

传入参数

注意

key 的取值请参考特效包的参数说明文件

setVideoEffectColorFilter

public abstract void com.ss.video.rtc.engine.RtcEngine.setVideoEffectColorFilter(
    String resFile)

设置颜色滤镜

传入参数

setVideoEffectColorFilterIntensity

public abstract void com.ss.video.rtc.engine.RtcEngine.setVideoEffectColorFilterIntensity(
    float intensity)

设置颜色滤镜强度

传入参数

ByteAudioFrame

public class com.ss.video.rtc.engine.utils.ByteAudioFrame

音频帧数据封装

成员变量

变量说明

samples

public byte[] com.ss.video.rtc.engine.utils.ByteAudioFrame.samples;

音频pcm数据

numOfSamples

public int com.ss.video.rtc.engine.utils.ByteAudioFrame.numOfSamples;

音频数据的采样点个数

bytesPerSample

public int com.ss.video.rtc.engine.utils.ByteAudioFrame.bytesPerSample;

音频数据的每个采样点的字节数（位深）

channels

public int com.ss.video.rtc.engine.utils.ByteAudioFrame.channels;

音频数据的采样通道数

samplesPerSec

public int com.ss.video.rtc.engine.utils.ByteAudioFrame.samplesPerSec;

音频数据的采样率

VideoCanvas

public class com.ss.video.rtc.engine.VideoCanvas

SDK的渲染画布，可以通过 setupLocalVideo setupRemoteVideo 给SDK设置渲染View

成员变量

变量说明

BYTERTC_RENDER_HIDDEN

public static final int com.ss.video.rtc.engine.VideoCanvas.BYTERTC_RENDER_HIDDEN = 1;

SDK渲染模式，HIDDEN模式（图像等比放大，充满屏幕，多余部分会裁剪）

BYTERTC_RENDER_FIT

public static final int com.ss.video.rtc.engine.VideoCanvas.BYTERTC_RENDER_FIT = 2;

SDK渲染模式，FIT模式（图像保持比例，会在画布中完全显示，画布多余部分会显示黑边）

BYTERTC_RENDER_ADAPTIVE

public static final int com.ss.video.rtc.engine.VideoCanvas.BYTERTC_RENDER_ADAPTIVE = 3;

已经废弃，SDK不支持，设置后图像会变形

renderView

public View com.ss.video.rtc.engine.VideoCanvas.renderView;

需要渲染的View

renderMode

public int com.ss.video.rtc.engine.VideoCanvas.renderMode;

SDK渲染模式

roomId

public String com.ss.video.rtc.engine.VideoCanvas.roomId;

房间ID

uid

public String com.ss.video.rtc.engine.VideoCanvas.uid;

用户ID

isScreen

public boolean com.ss.video.rtc.engine.VideoCanvas.isScreen;

是否是屏幕流

RtcVideoFrame

public class com.ss.video.rtc.engine.mediaio.RtcVideoFrame

视频帧

成员变量

变量说明

buffer

public ByteBuffer com.ss.video.rtc.engine.mediaio.RtcVideoFrame.buffer;

视频数据缓冲区

extend_data

public ByteBuffer com.ss.video.rtc.engine.mediaio.RtcVideoFrame.extend_data;

视频扩展数据

supplementary_info

public ByteBuffer com.ss.video.rtc.engine.mediaio.RtcVideoFrame.supplementary_info;

补充数据

buffer_type

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.buffer_type;

缓冲区类型

format

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.format;

视频帧数据格式

stride

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.stride;

视频帧数据跨距

height

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.height;

视频帧分辨率高度

rotation

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.rotation;

旋转角度

timestamp

public long com.ss.video.rtc.engine.mediaio.RtcVideoFrame.timestamp;

视频帧时间戳

cropLeft

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.cropLeft = 0;

指定左边裁剪掉的像素数量。默认为 0

cropTop

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.cropTop = 0;

指定顶边裁剪掉的像素数量。默认为 0

cropRight

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.cropRight = 0;

指定右边裁剪掉的像素数量。默认为 0

cropBottom

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.cropBottom = 0;

指定底边裁剪掉的像素数量。默认为 0

eglContext11

public EGLContext com.ss.video.rtc.engine.mediaio.RtcVideoFrame.eglContext11 = null;

EGL Context

eglContext14

public android.opengl.EGLContext com.ss.video.rtc.engine.mediaio.RtcVideoFrame.eglContext14 = null;

EGL上下文

glTarget

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.glTarget;

textureId

public int com.ss.video.rtc.engine.mediaio.RtcVideoFrame.textureId;

视频帧使用纹理的Id

transform

public float[] com.ss.video.rtc.engine.mediaio.RtcVideoFrame.transform = null;

传入一个 4x4 的变换矩阵，典型值是传入一个单位矩阵

VideoStreamDescription

public class com.ss.video.rtc.engine.VideoStreamDescription

视频信息描述

成员变量

变量说明

videoSize

public Pair<Integer, Integer> com.ss.video.rtc.engine.VideoStreamDescription.videoSize;

视频大小

frameRate

public int com.ss.video.rtc.engine.VideoStreamDescription.frameRate;

视频帧率

maxKbps

public int com.ss.video.rtc.engine.VideoStreamDescription.maxKbps;

最大码率

scaleMode

public ScaleMode com.ss.video.rtc.engine.VideoStreamDescription.scaleMode = ScaleMode.Auto;

缩放策略，默认是拉伸

encodePreference

public EncoderPreference com.ss.video.rtc.engine.VideoStreamDescription.encodePreference = EncoderPreference.MaintainFramerate;

编码策略偏好