RTCEngine

public abstract class com.ss.bytertc.engine.RTCEngine

RtcEngine接口

静态函数

成员函数

函数说明

createEngine

public static synchronized RTCEngine com.ss.bytertc.engine.RTCEngine.createEngine(
    Context context,
    String appId,
    IRTCEngineEventHandler handler,
    Object eglContext,
    JSONObject parameters)

创建引擎对象
如果当前线程中未创建引擎实例，那么你必须先使用此方法，以使用 RTC 提供的各种音视频能力。
如果当前线程中已创建了引擎实例，再次调用此方法时，会创建另一个独立的引擎实例。

传入参数

返回值

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

注意

• 你应注意保持 handler 的生命周期必须大于 RTCEngine 的生命周期，即 handler 必须在调用 createEngine 之前创建，在调用 destroyEngine 之后销毁。

• 如果你在同一个线程中创建了多个引擎实例，这些实例必须分别调用 destroyEngine 销毁。

• 通常不建议在移动端设备上创建多于 2 个引擎实例。

destroyEngine

public static synchronized void com.ss.bytertc.engine.RTCEngine.destroyEngine(
    RTCEngine engine)

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

注意

• 请确保和需要销毁的 RTCEngine 实例相关的业务场景全部结束后，才调用此方法
• 该方法在调用之后，会销毁所有和此 RTCEngine 实例相关的内存，并且停止与媒体服务器的任何交互
• 本方法为阻塞调用，会阻塞当前线程直到SDK彻底完成退出逻辑，因而需要注意不要在回调线程中直接调用 本方法，也需要注意不要在回调方法中等待主线程的执行，而同时在主线程调用本方法，从而造成死锁

getSdkVersion

public static String com.ss.bytertc.engine.RTCEngine.getSdkVersion()

获取 SDK 当前的版本号。

返回值 SDK 当前的版本号。

getErrorDescription

public static String com.ss.bytertc.engine.RTCEngine.getErrorDescription(
    int code)

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

传入参数

返回值 String 描述文字

setRtcEngineEventHandler

public abstract void com.ss.bytertc.engine.RTCEngine.setRtcEngineEventHandler(
    IRTCEngineEventHandler engineEventHandler)

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

传入参数

注意

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

joinRoom

public abstract int com.ss.bytertc.engine.RTCEngine.joinRoom(
    String token,
    String roomId,
    UserInfo userInfo,
    RTCRoomConfig roomConfig)

创建/加入房间：房间不存在时即创建房间；房间存在时即加入这个房间。
同一房间内的用户间可以相互通话。
进房后重复调用无效，用户必须调用 leaveRoom 退出当前房间后，才能加入下一个房间。

传入参数

返回值

• 0：方法调用成功。
• -1：roomID / userInfo.uid 包含了无效的参数。
• -2：已经在房间内。接口调用成功后，只要收到返回值为 0 ，且未调用 leaveRoom 成功，则再次调用进房接口时，无论填写的房间 ID 和用户 ID 是否重复，均触发此返回值。
• -3：native engine 为空

注意

• 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后进房的用户会将先进房的用户踢出房间，并且先进房的用户会收到 onError 回调通知，错误类型详见 ErrorCode 中的 kErrorCodeDuplicateLogin。
• 本地用户调用此方法加入房间成功后，会收到 onJoinRoomResult 回调通知。
• 本地用户调用 setUserVisibility 将自身设为可见后加入房间，远端用户会收到 onUserJoined 回调通知。
• 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本地会收到 onJoinRoomResult 回调通知；如果加入房间的用户是主播角色，远端用户会收到 onUserJoined 回调通知。

leaveRoom

public abstract int com.ss.bytertc.engine.RTCEngine.leaveRoom()

离开房间。
用户调用此方法离开房间，结束通话过程，释放所有通话相关的资源。
此方法是异步操作，调用返回时并没有真正退出房间。真正退出房间后，本地会收到 onLeaveRoom 回调通知。

返回值

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

注意

• 可见的用户离开房间后，房间内其他用户会收到 onUserLeave 回调通知。
• 如果调用此方法后立即销毁引擎，SDK 将无法触发 onLeaveRoom 回调。
• 调用 joinRoom 方法加入房间后，必须调用此方法结束通话，否则无法开始下一次通话。无论当前是否在房间内，都可以调用此方法。重复调用此方法没有负面影响。

startVideoCapture

public abstract void com.ss.bytertc.engine.RTCEngine.startVideoCapture()

立即开启内部视频采集。默认为关闭状态。
内部视频采集指：使用 RTC SDK 内置视频采集模块，进行采集。
调用该方法后，本地用户会收到 onMediaDeviceStateChanged 的回调。
本地用户在非隐身状态下调用该方法，房间中的其他用户会收到 onUserStartVideoCapture 的回调。

注意

• 调用 stopVideoCapture 可以停止内部视频采集。否则，只有当销毁引擎实例时，内部视频采集才会停止。
• 创建引擎后，无论是否发布视频数据，你都可以调用该方法开启内部视频采集。只有当（内部或外部）视频采集开始以后视频流才会发布。
• 如果需要从自定义视频采集切换为内部视频采集，你必须先停止发布流，关闭自定义采集，再调用此方法手动开启内部采集。
• 内部视频采集使用的摄像头由 switchCamera 接口指定。
• 你也可以联系技术支持同学，帮助你在服务端配置采集格式并下发到 Android 端。

stopVideoCapture

public abstract void com.ss.bytertc.engine.RTCEngine.stopVideoCapture()

立即关闭内部视频采集。默认为关闭状态。
内部视频采集指：使用 RTC SDK 内置视频采集模块，进行采集。 调用该方法，本地用户会收到 onMediaDeviceStateChanged 的回调。
调用该方法，房间中的其他用户会收到 onUserStopVideoCapture 的回调。

注意

• 调用 startVideoCapture 可以开启内部视频采集。
• 如果不调用本方法停止内部视频采集，则只有当销毁引擎实例时，内部视频采集才会停止。

startAudioCapture

public abstract void com.ss.bytertc.engine.RTCEngine.startAudioCapture()

开启内部音频采集。默认为关闭状态。
开启后，本地用户会收到 onMediaDeviceStateChanged 的回调。
进房后调用该方法，房间中的其他用户会收到 onUserStartAudioCapture 的回调。

注意

• 若未取得当前设备的麦克风权限，调用该方法后会触发 onWarning 回调。
• 调用 stopAudioCapture 可以关闭音频采集设备，否则，SDK 只会在销毁引擎的时候自动关闭设备。
• 无论是否发布音频数据，你都可以调用该方法开启音频采集，并且调用后方可发布音频。
• 尚未进房并且已使用自定义采集时，关闭自定义采集后并不会自动开启内部采集。你需调用此方法手动开启内部采集。
• 如果已开启外部音频采集，你必须在房间外调用 disableExternalAudioDevice 关闭外部音频采集，然后开启内部音频采集。

stopAudioCapture

public abstract void com.ss.bytertc.engine.RTCEngine.stopAudioCapture()

关闭内部音频采集。默认为关闭状态。
进房前调用该方法，本地用户会收到 onMediaDeviceStateChanged 的回调。
进房后调用该方法，房间中的其他用户会收到 onUserStopAudioCapture 的回调。

注意

• 调用 startAudioCapture 可以开启音频采集设备。
• 设备开启后若一直未调用该方法关闭设备，则 SDK 会在销毁引擎的时候自动关闭音频采集设备。

setAudioScenario

public abstract void com.ss.bytertc.engine.RTCEngine.setAudioScenario(
    AudioScenarioType audioScenario)

设置音频场景类型

传入参数

setAudioProfile

public abstract void com.ss.bytertc.engine.RTCEngine.setAudioProfile(
    AudioProfileType audioProfile)

设置音质档位。你应根据业务场景需要选择适合的音质档位。

传入参数

注意

• 该方法在进房前后均可调用；
• 支持通话过程中动态切换音质档位。

setVoiceChangerType

public abstract void com.ss.bytertc.engine.RTCEngine.setVoiceChangerType(
    VoiceChangerType voiceChanger)

设置变声特效类型

传入参数

注意

• 在进房前后都可设置。
• 对 RTC SDK 内部采集的音频和自定义采集的音频都生效。
• 只对单声道音频生效。
• 只在包含美声特效能力的 SDK 中有效。
• 与 setVoiceReverbType 互斥，后设置的特效会覆盖先设置的特效。

setVoiceReverbType

public abstract void com.ss.bytertc.engine.RTCEngine.setVoiceReverbType(
    VoiceReverbType voiceReverb)

设置混响特效类型

传入参数

注意

• 在进房前后都可设置。
• 对 RTC SDK 内部采集的音频和自定义采集的音频都生效。
• 只对单声道音频生效。
• 只在包含美声特效能力的 SDK 中有效。
• 与 setVoiceChangerType 互斥，后设置的特效会覆盖先设置的特效。

setLocalVideoCanvas

public abstract int com.ss.bytertc.engine.RTCEngine.setLocalVideoCanvas(
    StreamIndex streamIndex,
    VideoCanvas videoCanvas)

设置本地视频渲染时，使用的视图，并设置渲染模式。
你应在加入房间前，绑定本地视图。退出房间后，此设置仍然有效。 如果需要解除绑定，你可以调用本方法传入空视图。

传入参数

返回值

• 0: 成功
• -1: VideoCanvas 为空

setLocalVideoSink

public abstract void com.ss.bytertc.engine.RTCEngine.setLocalVideoSink(
    StreamIndex index,
    IVideoSink videoSink,
    @IVideoSink.PixelFormat int requiredFormat)

将本地视频流与自定义渲染器绑定。

传入参数

注意

• RTC SDK 默认使用 RTC SDK 自带的渲染器（内部渲染器）进行视频渲染。
• 进退房操作不会影响绑定状态。
• 如果需要解除绑定，你必须将 videoSink 设置为 null。
• 一般在收到 onFirstLocalVideoFrameCaptured 回调通知完成本地视频首帧采集后，调用此方法为视频流绑定自定义渲染器；然后加入房间。

setRemoteVideoSink

public abstract void com.ss.bytertc.engine.RTCEngine.setRemoteVideoSink(
    RemoteStreamKey streamKey,
    IVideoSink videoSink,
    @IVideoSink.PixelFormat int requiredFormat)

将远端视频流与自定义渲染器绑定。

传入参数

注意

• RTC SDK 默认使用 RTC SDK 自带的渲染器（内部渲染器）进行视频渲染。
• 该方法进房前后均可以调用。若想在进房前调用，你需要在加入房间前获取远端流信息；若无法预先获取远端流信息，你可以在加入房间并通过 onStreamAdd 回调获取到远端流信息之后，再调用该方法。
• 如果需要解除绑定，你必须将 videoSink 设置为 null。进退房操作不会影响绑定状态。

setRemoteVideoCanvas

public abstract int com.ss.bytertc.engine.RTCEngine.setRemoteVideoCanvas(
    String userId,
    StreamIndex streamIndex,
    VideoCanvas videoCanvas)

渲染来自指定远端用户的视频流时，设置使用的视图和渲染模式。
如果需要解除视频的绑定视图，把 videoCanvas 设置为空。

传入参数

返回值

• 0：成功
• < 0：失败

注意

• 你应在加入房间后，绑定视图。退出房间后，此设置不失效。

setLocalVideoMirrorType

public abstract int com.ss.bytertc.engine.RTCEngine.setLocalVideoMirrorType(
    MirrorType mirrorType)

为本地采集到的视频流开启镜像

传入参数

注意

• 该接口调用前，各视频源的初始状态如下：

• 切换视频源不影响镜像设置。
• 屏幕视频流始终不受镜像设置影响。

switchCamera

public abstract int com.ss.bytertc.engine.RTCEngine.switchCamera(
    CameraId cameraId)

切换视频内部采集时使用的前置/后置摄像头
调用此接口后，在本地会触发 onMediaDeviceStateChanged 回调。

传入参数

返回值

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

注意

• 默认使用前置摄像头。
• 如果你正在使用相机进行视频采集，切换操作当即生效；如果相机未启动，后续开启内部采集时，会打开设定的摄像头。

setAudioPlaybackDevice

public abstract int com.ss.bytertc.engine.RTCEngine.setAudioPlaybackDevice(
    AudioPlaybackDevice audioPlaybackDevice)

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

传入参数

返回值 方法调用结果

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

注意

• 该方法适用于手机等移动设备。
• 听筒和扬声器为移动设备自带的音频播放设备。听筒一般用于通话，扬声器一般用于外放。
• 连接有线或者蓝牙音频播放设备后，音频路由将切换至有线耳机或者蓝牙耳机。不同音频场景中，音频路由和发布订阅状态到音量类型的映射关系详见 AudioScenarioType 。
• 进房前和进房后，均可调用此方法设置音频播放设备。

muteLocalAudio

public abstract void com.ss.bytertc.engine.RTCEngine.muteLocalAudio(
    MuteState muteState)

控制本地音频流的发送状态：发送/不发送。
使用此方法后，房间中的其他用户会收到回调 onUserMuteAudio。

传入参数

注意 本方法仅控制本地音频流的发送状态，并不影响本地音频采集状态。

muteLocalVideo

public abstract void com.ss.bytertc.engine.RTCEngine.muteLocalVideo(
    MuteState muteState)

停止/启动发送本地视频流，默认不发送。
无论你使用内部视频采集，还是自定义视频采集，你都应使用此接口启动发送本地视频流。
调用该方法后，房间中的其他用户会收到 onUserMuteVideo 的回调。

传入参数

注意

• 本方法只是停止/启动本地视频流的发送，不影响视频采集状态。
• 无论是否开启视频采集，你都可以启动发送本地视频流。这样，一旦开始采集视频，即可进行发送。

pauseAllSubscribedStream

public abstract void com.ss.bytertc.engine.RTCEngine.pauseAllSubscribedStream(
    PauseResumeControlMediaType mediaType)

暂停接收来自远端的媒体流。

传入参数

注意

• 该方法仅暂停远端流的接收，并不影响远端流的采集和发送；
• 该方法不改变用户的订阅状态以及订阅流的属性。
• 若想恢复接收远端流，需调用 resumeAllSubscribedStream。

resumeAllSubscribedStream

public abstract void com.ss.bytertc.engine.RTCEngine.resumeAllSubscribedStream(
    PauseResumeControlMediaType mediaType)

恢复接收来自远端的媒体流

传入参数

注意

• 该方法仅恢复远端流的接收，并不影响远端流的采集和发送；
• 该方法不改变用户的订阅状态以及订阅流的属性。

updateToken

public abstract int com.ss.bytertc.engine.RTCEngine.updateToken(
    String token)

更新 Token。
用于加入房间的 Token 有一定的有效期。当 Token 过期时，需要调用此方法更新房间的 Token 信息。
调用 joinRoom 方法加入房间或断网重连进入房间时，如果 Token 过期，将导致加入房间失败，并会收到 onJoinRoomResult 回调通知，回调错误码为 ErrorCode 中的 ERROR_CODE_INVALID_TOKEN。此时需要重新获取 Token，并调用此方法更新 Token。

传入参数

返回值 方法调用结果。

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

注意

• 如果因 Token 过期导致加入房间失败，则调用此方法更新 Token 后，SDK 会自动重新加入房间，不需要再次调用 joinRoom 方法。
• Token 过期时，如果已经加入房间成功，则不会受到影响。

setUserVisibility

public abstract int com.ss.bytertc.engine.RTCEngine.setUserVisibility(
    boolean enable)

设置用户可见性。默认可见。
通过设置用户的可见性，可以控制用户在房间内的行为：

• 能否发布音视频流；
  
• 用户自身是否在房间中隐身。
  

传入参数

返回值

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

注意

• 该方法在加入房间前后均可调用。
• 在房间内调用此方法，房间内其他用户会收到相应的回调通知：
• 从 false 切换至 true 时，房间内其他用户会收到 onUserJoined 回调通知；
• 从 true 切换至 false 时，房间内其他用户会收到 onUserLeave 回调通知。
• 若调用该方法将可见性设为 false，此时尝试发布流会收到 onWarning 警告，具体原因参看 WarningCode 中的 kWarningCodePublishStreamForbiden 警告码。

publish

public abstract int com.ss.bytertc.engine.RTCEngine.publish()

在当前所在房间内开始发布本地音视频流

注意 1.多房间模式下，默认音视频流不自动发布。你必须调用此接口，进行手动发布。 2.调用 setUserVisibility 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布音视频流。 3.用户在房间内，同一时间仅能在一个房间内发布音视频流。 4.用户调用此方法成功发布音视频流后，房间中的其他用户将会收到 onStreamAdd 回调通知。

unpublish

public abstract int com.ss.bytertc.engine.RTCEngine.unpublish()

在当前所在房间内停止发布本地音视频流。

注意

• 在多房间模式下，调用 publish 手动发布音视频流后，调用此接口停止发布。
• 用户调用此方法停止发布音视频流后，房间中的其他用户将会收到 onStreamRemove 回调通知。

setCaptureVolume

public abstract void com.ss.bytertc.engine.RTCEngine.setCaptureVolume(
    StreamIndex index,
    int volume)

调节音频采集音量

传入参数

注意

• 无论是采集来自麦克风的音频流，还是屏幕音频流；无论是 RTC SDK 内部采集，还是自定义采集，都可以使用此接口进行音量调节。
• 在开启音频采集前后，你都可以使用此接口设定采集音量。

setPlaybackVolume

public abstract void com.ss.bytertc.engine.RTCEngine.setPlaybackVolume(
    int volume)

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

传入参数

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

setLocalVoicePitch

public abstract void com.ss.bytertc.engine.RTCEngine.setLocalVoicePitch(
    int pitch)

开启本地语音变调功能，多用于 K 歌场景。
使用该方法，你可以对本地语音的音调进行升调或降调等调整。

传入参数

sendRoomMessage

public abstract long com.ss.bytertc.engine.RTCEngine.sendRoomMessage(
    String messageStr)

给房间内的所有其他用户群发文本消息。

传入参数

返回值

>0：发送成功，返回这次发送消息的编号，从 1 开始递增

-1：发送失败

注意

• 在房间内广播文本消息前，必须先调用 joinRoom 加入房间。
• 调用后，会收到 onRoomMessageSendResult 回调；
• 同一房间内的其他用户会收到 onRoomMessageReceived 回调。

sendRoomBinaryMessage

public abstract long com.ss.bytertc.engine.RTCEngine.sendRoomBinaryMessage(
    byte[] buffer)

给房间内的所有其他用户群发二进制消息。

传入参数

返回值

>0：发送成功，返回这次发送消息的编号，从 1 开始递增

-1：发送失败

注意

• 在房间内广播二进制消息前，必须先调用 joinRoom 加入房间。
• 调用后，会收到 onRoomMessageSendResult 回调；
• 同一房间内的其他用户会收到 onRoomBinaryMessageReceived 回调。

sendUserMessage

public abstract long com.ss.bytertc.engine.RTCEngine.sendUserMessage(
    String userId,
    String messageStr)

给房间内指定的用户发送点对点文本消息。

传入参数

返回值

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

注意

• 在发送房间内文本消息前，必须先调用 joinRoom 加入房间。
• 调用后，会收到 onUserMessageSendResult 回调，通知消息发送成功或失败；
• 若消息发送成功，则 userId 所指定的用户会收到 onUserMessageReceived 回调。

sendUserBinaryMessage

public abstract long com.ss.bytertc.engine.RTCEngine.sendUserBinaryMessage(
    String userId,
    byte[] buffer)

给房间内指定的用户发送点对点二进制消息。

传入参数

返回值

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

注意

• 在发送房间内二进制消息前，必须先调用 joinRoom 加入房间。
• 调用后，会收到 onUserMessageSendResult 回调，通知消息发送成功或失败；
• 若消息发送成功，则 userId 所指定的用户会收到 onUserBinaryMessageReceived 回调。

login

public abstract void com.ss.bytertc.engine.RTCEngine.login(
    String token,
    String uid)

必须先登录注册一个 uid，才能发送房间外消息和向业务服务器发送消息

传入参数

注意

• 在调用本接口登录后，如果想要登出，需要调用 logout。
• 本地用户调用此方法登录成功后，会收到 onLoginResult 回调通登录结果，远端用户不会收到通知。

logout

public abstract void com.ss.bytertc.engine.RTCEngine.logout()

调用本接口登出后，无法调用房间外消息以及端到服务器消息相关的方法或收到相关回调。

注意

• 调用本接口登出后，必须先调用 login 登录。
• 本地用户调用此方法登出后，会收到 onLogout 回调通知结果，远端用户不会收到通知。

updateLoginToken

public abstract void com.ss.bytertc.engine.RTCEngine.updateLoginToken(
    String token)

更新用户用于登录的 Token
Token 有一定的有效期，当 Token 过期时，需调用此方法更新登录的 Token 信息。
调用 login 方法登录时，如果使用了过期的 Token 将导致登录失败，并会收到 onLoginResult 回调通知，错误码为 LOGIN_ERROR_CODE_INVALID_TOKEN。此时需要重新获取 Token，并调用此方法更新 Token。

传入参数

注意

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

setServerParams

public abstract void com.ss.bytertc.engine.RTCEngine.setServerParams(
    String signature,
    String url)

设置业务服务器参数
客户端调用 sendServerMessage 或 sendServerBinaryMessage 发送消息给业务服务器之前，必须需要设置有效签名和业务服务器地址。

传入参数

注意

• 用户必须调用 login 登录后，才能调用本接口。
• 调用本接口后，SDK 会使用 onServerParamsSetResult 返回相应结果。

getPeerOnlineStatus

public abstract void com.ss.bytertc.engine.RTCEngine.getPeerOnlineStatus(
    String peer_user_id)

查询对端用户或本端用户的登录状态

传入参数

注意

• 必须调用 login 登录后，才能调用本接口。
• 调用本接口后，SDK 会使用 onGetPeerOnlineStatus 回调通知查询结果。
• 在发送房间外消息之前，用户可以通过本接口了解对端用户是否登录，从而决定是否发送消息。也可以通过本接口查询自己查看自己的登录状态。

sendUserMessageOutsideRoom

public abstract long com.ss.bytertc.engine.RTCEngine.sendUserMessageOutsideRoom(
    String uid,
    String message)

给房间外指定的用户发送文本消息（P2P）

传入参数

返回值

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

注意

• 在发送房间外文本消息前，必须先调用 login 完成登录。
• 用户调用本接口发送文本信息后，会收到一次 onUserMessageSendResultOutsideRoom 回调，得知消息是否成功发送。
• 若文本消息发送成功，则 uid 所指定的用户会通过 onUserMessageReceivedOutsideRoom 回调收到该消息。

sendUserBinaryMessageOutsideRoom

public abstract long com.ss.bytertc.engine.RTCEngine.sendUserBinaryMessageOutsideRoom(
    String uid,
    byte[] buffer)

给房间外指定的用户发送二进制消息（P2P）

传入参数

返回值

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

注意

• 在发送房间外二进制消息前，必须先调用 login 完成登录。
• 用户调用本接口发送二进制消息后，会收到一次 onUserMessageSendResultOutsideRoom 回调，通知消息是否发送成功；
• 若二进制消息发送成功，则 uid 所指定的用户会通过 onUserBinaryMessageReceivedOutsideRoom 回调收到该条消息。

sendServerMessage

public abstract long com.ss.bytertc.engine.RTCEngine.sendServerMessage(
    String message)

客户端给业务服务器发送文本消息（P2Server）

传入参数

返回值

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

注意

• 在向业务服务器发送文本消息前，必须先调用 login 完成登录，随后调用 setServerParams 设置业务服务器。
• 调用本接口后会收到一次 onServerMessageSendResult 回调，通知消息发送方是否发送成功。
• 若文本消息发送成功，则之前调用 setServerParams 设置的业务服务器会收到该条消息。

sendServerBinaryMessage

public abstract long com.ss.bytertc.engine.RTCEngine.sendServerBinaryMessage(
    byte[] buffer)

客户端给业务服务器发送二进制消息（P2Server）

传入参数

返回值

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

注意

• 在向业务服务器发送二进制消息前，必须先调用 login 完成登录，随后调用 setServerParams 设置业务服务器。
• 调用本接口后，会收到一次 onServerMessageSendResult 回调，通知消息发送方发送成功或失败；
• 若二进制消息发送成功，则之前调用 setServerParams 设置的业务服务器会收到该条消息。

startNetworkDetection

public abstract IRTCEngineEventHandler.NetworkDetectionStartReturn com.ss.bytertc.engine.RTCEngine.startNetworkDetection(
    boolean isTestUplink,
    int expectedUplinkBitrate,
    boolean isTestDownlink,
    int expectedDownlinkBitrate)

开启通话前网络探测

传入参数

返回值 开启通话前网络探测结果，详见 NetworkDetectionStartReturn

注意

• 成功调用本接口后，每 2s 会收到一次 onNetworkDetectionResult 回调，通知探测结果；
• 若探测停止，则会收到一次 onNetworkDetectionStopped 通知探测停止。

stopNetworkDetection

public abstract void com.ss.bytertc.engine.RTCEngine.stopNetworkDetection()

停止通话前网络探测

注意

• 调用本接口后，会收到一次 onNetworkDetectionStopped 回调通知探测停止。

setRecordingAudioFrameParameters

public abstract boolean com.ss.bytertc.engine.RTCEngine.setRecordingAudioFrameParameters(
    int sampleRate,
    int channels)

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

传入参数

返回值 方法调用结果

• true：方法调用成功
• false：方法调用失败

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

setPlaybackAudioFrameParameters

public abstract boolean com.ss.bytertc.engine.RTCEngine.setPlaybackAudioFrameParameters(
    int sampleRate,
    int channels)

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

传入参数

返回值 方法调用结果

• true：方法调用成功
• false：方法调用失败

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

setMixedAudioFrameParameters

public abstract boolean com.ss.bytertc.engine.RTCEngine.setMixedAudioFrameParameters(
    int sampleRate,
    int channels)

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

传入参数

返回值 方法调用结果

• true：方法调用成功
• false：方法调用失败

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

registerAudioFrameObserver

public abstract int com.ss.bytertc.engine.RTCEngine.registerAudioFrameObserver(
    IAudioFrameObserver observer)

注册音频数据回调观察者

传入参数

返回值 方法调用结果

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

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

registerLocalAudioProcessor

public abstract int com.ss.bytertc.engine.RTCEngine.registerLocalAudioProcessor(
    IAudioProcessor audioProcessor,
    AudioFormat audioFormat)

设置自定义音频处理器。
使用该处理器，你可以调用 processAudioFrame 对 RTC SDK 采集得到的音频帧进行自定义处理，并将处理后的音频帧用于 RTC 音视频通信。
SDK 只持有 processor 的弱引用，你应保证其生命周期。

传入参数

注意 重复调用此接口时，仅最后一次调用生效。效果不会叠加。

registerLocalVideoProcessor

public abstract int com.ss.bytertc.engine.RTCEngine.registerLocalVideoProcessor(
    IVideoProcessor processor,
    VideoPreprocessorConfig config)

设置自定义视频前处理器。
使用这个视频前处理器，你能够调用 processVideoFrame 对 RTC SDK 采集得到的视频帧进行前处理，并将处理后的视频帧用于 RTC 音视频通信。

传入参数

返回值

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

注意 经前处理后，返回给 RTC SDK 的视频帧格式仅支持 I420 和 TEXTURE_2D。

registerLocalEncodedVideoFrameObserver

public abstract void com.ss.bytertc.engine.RTCEngine.registerLocalEncodedVideoFrameObserver(
    ILocalEncodedVideoFrameObserver observer)

注册本地视频帧监测器。
无论使用内部采集还是自定义采集，调用该方法后，SDK 每监测到一帧本地视频帧时，都会将视频帧信息通过 onLocalEncodedVideoFrame 回调给用户

传入参数

注意 该方法可在进房前后的任意时间调用，越早调用越早监测视频帧

setVideoSourceType

public abstract void com.ss.bytertc.engine.RTCEngine.setVideoSourceType(
    StreamIndex index,
    VideoSourceType type)

设置向 SDK 输入的视频源

传入参数

注意

• 默认使用内部采集。内部采集指：使用 RTC SDK 内置的视频采集机制进行视频采集。
• 该方法进房前后均可调用。
• 当你已调用 startVideoCapture 开启内部采集后，再调用此方法切换至自定义采集时，SDK 会自动关闭内部采集。
• 当你调用此方法开启自定义采集后，想要切换至内部采集，你必须先调用此方法关闭自定义采集，然后调用 startVideoCapture 手动开启内部采集。
• 当你需要向 SDK 推送自定义编码后的视频帧，你需调用该方法将视频源切换至自定义编码视频源。

pushExternalVideoFrame

public abstract boolean com.ss.bytertc.engine.RTCEngine.pushExternalVideoFrame(
    VideoFrame frame)

推送外部视频帧。

传入参数

返回值

• true: 成功
• false: 失败

注意

• 该方法主动将视频帧数据用 VideoFrame 类封装后传递给 SDK。
• 请确保在你调用本方法前已调用 setVideoSourceType 设置为自定义视频采集。
• 当使用纹理数据时， 确保 createEngine中的eglContext与frame中的eglContext为sharedContext或者相同，否则会无法编码

pushExternalVideoFrame

public abstract boolean com.ss.bytertc.engine.RTCEngine.pushExternalVideoFrame(
    VideoFrame frame,
    boolean isDirectEncode)

推送外部视频帧。

传入参数

返回值

• true: 成功
• false: 失败

注意

• 该方法主动将视频帧数据用 VideoFrame 类封装后传递给 SDK。
• 请确保在你调用本方法前已调用 setVideoSourceType 设置为自定义视频采集。
• 当使用纹理数据时， 确保 createEngine中的eglContext与frame中的eglContext为sharedContext或者相同，否则会无法编码

startLiveTranscoding

public abstract void com.ss.bytertc.engine.RTCEngine.startLiveTranscoding(
    LiveTranscoding liveTranscode,
    ILiveTranscodingObserver observer)

开启转推直播，并设置合流的视频视图布局和音频属性。

传入参数

注意

• 只有房间模式为直播模式的用户才能调用此方法。
• 调用该方法后，关于启动结果和推流过程中的错误，会收到 onStreamMixingEvent 回调。
• 调用 stopLiveTranscoding 停止转推直播。

stopLiveTranscoding

public abstract void com.ss.bytertc.engine.RTCEngine.stopLiveTranscoding()

停止转推直播。
关于启动转推直播，参看 startLiveTranscoding。

updateLiveTranscoding

public abstract void com.ss.bytertc.engine.RTCEngine.updateLiveTranscoding(
    LiveTranscoding transcoding)

更新转推直播参数。
使用 startLiveTranscoding 启用转推直播功能后，使用此方法更新功能配置参数。

传入参数

setVideoCaptureConfig

public abstract int com.ss.bytertc.engine.RTCEngine.setVideoCaptureConfig(
    VideoCaptureConfig videoCaptureConfig)

设置 RTC SDK 内部采集时的视频采集参数。
如果你的项目使用了 SDK 内部采集模块，可以通过本接口指定视频采集参数包括分辨率、帧率。

传入参数

返回值

• 0: 成功；
• < 0: 失败；

注意

• 本接口在引擎创建后即可调用，建议在调用 startVideoCapture 前调用本接口。
• 建议同一设备上的不同 Engine 使用相同的视频采集参数。
• 如果调用本接口前使用内部模块开始视频采集，采集参数默认为 setVideoEncoderConfig 中设置的参数。

setVideoEncoderConfig

public abstract int com.ss.bytertc.engine.RTCEngine.setVideoEncoderConfig(
    List<VideoStreamDescription> videoStreamDescriptions)

启动推送多路视频流，设置推送多路流时的各路视频参数，包括分辨率、帧率、码率、缩放模式、网络不佳时的回退策略等。

传入参数

返回值

• 0：成功
• !0：失败

注意

• 当使用内部采集时，视频采集的分辨率、帧率会根据最大的编码分辨率、帧率进行适配
• 默认的视频编码参数为：分辨率 640px
• 变更编码分辨率后马上生效，可能会引发相机重启。
• 屏幕流只取视频参数数组的第一组数据。

subscribeUserStream

public abstract void com.ss.bytertc.engine.RTCEngine.subscribeUserStream(
    String uid,
    StreamIndex streamType,
    SubscribeMediaType mediaType,
    SubscribeVideoConfig subscribeVideoConfig)

订阅房间内指定的远端音视频流。
无论自动订阅还是手动订阅模式，你都可以调用此方法按需订阅房间中的音视频流。
该方法也可用于更新已经订阅的流的属性、媒体类型等配置。

传入参数

注意

• 你可以通过 onStreamAdd 和 onStreamRemove 两个回调获取当前房间你的音视频流信息，并调用本方法按需订阅流或修改订阅配置。
• 若订阅失败，你会收到 onRoomError 回调通知，具体失败原因参看 ErrorCode。
• 若调用 pauseAllSubscribedStream 暂停接收远端音视频流，此时仍可使用该方法对暂停接收的流进行设置，你会在调用 resumeAllSubscribedStream 恢复接收流后收到修改设置后的流。

enableExternalAudioDevice

public abstract void com.ss.bytertc.engine.RTCEngine.enableExternalAudioDevice(
    AudioFormat recordingFormat,
    AudioFormat playbackFormat)

启用自定义音频采集和渲染。

传入参数

注意

• 必须在进房前调用此方法；退房后，此设置自动失效。
• 必须同时启用自定义音频采集和自定义音频渲染，或同时启用内部音频采集和内部音频渲染。默认使用内部音频采集和渲染。
• 启用自定义音频采集和渲染后，使用 pushExternalAudioFrame，推送外部采集的音频数据到 RTC SDK 用于传输；使用 pullExternalAudioFrame 获取远端音频数据。
• 如果已调用 startAudioCapture 开启内部音频采集后，再调用此方法切换至自定义音频采集时，SDK 会自动关闭内部采集。
• 如果已开启自定义采集，需要切换至内部采集，必须调用 disableExternalAudioDevice 关闭自定义采集，然后调用 startAudioCapture 手动开启内部采集。

disableExternalAudioDevice

public abstract void com.ss.bytertc.engine.RTCEngine.disableExternalAudioDevice()

禁用已开启的自定义音频采集和渲染。

注意

• 如果已开启自定义采集，需要切换至内部采集，必须禁用已开启的自定义音频采集和渲染，然后调用 startAudioCapture 手动开启内部采集。
• 要启用自定义音频采集和渲染，调用 enableExternalAudioDevice。

pushExternalAudioFrame

public abstract int com.ss.bytertc.engine.RTCEngine.pushExternalAudioFrame(
    AudioFrame audioFrame)

推送外部采集的音频数据到 RTC SDK。

传入参数

返回值 方法调用结果

• 0: 设置成功
• < 0: 设置失败

注意

• 推送外部音频数据前，必须先调用 enableExternalAudioDevice 开启自定义采集。
• 你必须每隔 10 毫秒推送一次外部采集的音频数据。单次推送的 samples (音频采样点个数）应该为 audioFrame.sampleRate / 100。比如设置采样率为 48000 时， 每次应该推送 480 个采样点。
• 本方法中设置的 sampleRate（音频采样率） 和 channel（音频声道） 必须与 enableExternalAudioDevice 中设置的 sampleRate 和 channel 保持一致。
• 音频采样格式必须为 S16。音频缓冲区内的数据格式必须为 PCM 数据，其容量大小应该为 audioFrame.samples
• 该函数运行在用户级线程内。若同时运行其他进程，将导致本进程中断。

pullExternalAudioFrame

public abstract int com.ss.bytertc.engine.RTCEngine.pullExternalAudioFrame(
    AudioFrame audioFrame)

拉取音频数据，用于外部播放。

传入参数

返回值 方法调用结果

• 0: 设置成功
• < 0: 设置失败

注意

• 拉取外部音频数据前，必须先调用 enableExternalAudioDevice 启用自定义音频采集和渲染。
• 你应当每隔 10 毫秒拉取一次音频数据。samples (音频采样点个数）应该为 audioFrame.sampleRate / 100。如设置采样率为 48000 时， 每次应该拉取 480 个采样点。
• 调用本方法拉取的音频数据的 sampleRate（音频采样率） 和 channel（音频声道） 和 enableExternalAudioDevice 中设置的 sampleRate 和 channel 一致。即使远端音频采集设置的参数和本地通过 enableExternalAudioDevice 设置的参数不一致时，拉取到的音频数据的参数仍然和本地设置的值一致。
• 音频采样格式为 S16。音频缓冲区内的数据格式为 PCM 数据，其容量大小为 audioFrame.samples
• 该函数运行在用户级线程内。若同时运行其他进程，将导致本进程中断。

publishScreen

public abstract int com.ss.bytertc.engine.RTCEngine.publishScreen()

发布本地屏幕共享流。

返回值

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

注意

• 你必须先加入房间，才能调用此方法。
• 该方法仅适用于调用 setUserVisibility 方法将自身设为可见的用户。
• 此方法只影响屏幕共享视频流的发布状态，并不影响屏幕视频流的采集情况。你可以通过两种方式进行采集：
• RTC SDK 内部采集：参看 startScreenVideoCapture
• RTC SDK 外部采集：你可以自行采集屏幕音视频流，并周期性调用 pushScreenFrame 和 pushScreenAudioFrame 将采集得到的音视频帧推送到 RTC SDK 用于编码传输。
• 调用后，远端会收到 onStreamAdd 回调。
• 调用后，本地会收到 onFirstLocalVideoFrameCaptured 回调。
• 调用 unpublishScreen 取消发布。

unpublishScreen

public abstract int com.ss.bytertc.engine.RTCEngine.unpublishScreen()

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

返回值

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

注意

• 要开启发布，调用 publishScreen。
• 调用后，远端会收到 onStreamRemove 回调。

startScreenVideoCapture

public abstract int com.ss.bytertc.engine.RTCEngine.startScreenVideoCapture(
    Intent mediaProjectionResultData)

使用 RTC SDK 提供的采集模块，采集当前屏幕视频流，用于共享。

传入参数

返回值

• 0 :开启成功
• -1 :开启失败

注意

• 调用此方法仅开启屏幕流视频采集，不会发布采集到的视频。发布屏幕流视频需要调用 publishScreen。
• 要关闭屏幕视频源采集，调用 stopScreenVideoCapture。
• 调用成功后，本端会收到 onFirstLocalVideoFrameCaptured 回调。
• 调用此接口前，你可以调用 setVideoEncoderConfig 设置屏幕视频流的采集帧率和编码分辨率。

stopScreenVideoCapture

public abstract int com.ss.bytertc.engine.RTCEngine.stopScreenVideoCapture()

停止屏幕视频流采集。

返回值

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

注意 调用此接口不影响屏幕视频流发布。

pushScreenFrame

public abstract boolean com.ss.bytertc.engine.RTCEngine.pushScreenFrame(
    VideoFrame videoFrame)

推送屏幕视频帧

传入参数

返回值

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

setRemoteAudioPlaybackVolume

public abstract void com.ss.bytertc.engine.RTCEngine.setRemoteAudioPlaybackVolume(
    String uid,
    int volume)

调节来自指定远端用户的音频播放音量，默认为 100。

传入参数

createRoom

public abstract IRTCRoom com.ss.bytertc.engine.RTCEngine.createRoom(
    String roomId)

创建房间

传入参数

返回值 IRtcRoom 创建的房间IRtcRoom

注意

• 用户可以多次调用此方法创建多个 IRTCRoom 对象，再分别调用各 IRTCRoom 对象的 joinRoom 方法，实现同时加入多个房间；
• 加入多个房间后，用户可以同时订阅各房间的音视频流，同一时间仅能在一个房间内发布音视频流。

setPublishFallbackOption

public abstract int com.ss.bytertc.engine.RTCEngine.setPublishFallbackOption(
    PublishFallbackOption option)

设置发布的音视频流回退选项。
你可以调用这个接口来设置网络情况不佳或性能不足时只发送小流，以保证通话质量。

传入参数

返回值

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

注意

• 这个方法只在设置了发送多个流的情况下有效。
• 你必须在进房前设置，进房后设置或更改设置无效。

• 设置回退选项后，本端发布的音视频流发生回退或从回退中恢复时，对端会收到 onSimulcastSubscribeFallback 回调通知。

• 你可以调用 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。

setRemoteSubscribeFallbackOption

public abstract int com.ss.bytertc.engine.RTCEngine.setRemoteSubscribeFallbackOption(
    SubscribeFallbackOptions option)

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

传入参数

返回值

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

注意

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

setRemoteUserPriority

public abstract int com.ss.bytertc.engine.RTCEngine.setRemoteUserPriority(
    String uid,
    RemoteUserPriority priority)

设置用户优先级。

传入参数

返回值

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

注意

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

sendSEIMessage

public abstract int com.ss.bytertc.engine.RTCEngine.sendSEIMessage(
    StreamIndex streamIndex,
    byte[] message,
    int repeatCount)

在视频通信时，通过视频帧发送 SEI 数据。

传入参数

返回值

• >=0: 将被添加到视频帧中的 SEI 的数量
• < 0: 发送失败

注意

• 你可以通过此接口对 RTC SDK 内部采集的视频帧添加 SEI。对于采用自定义采集获得的视频帧：如果原视频帧中没有添加 SEI 数据，那么你可以调用此接口为其中添加 SEI 信息后，进行编码传输；如果原视频帧中已添加了 SEI 数据，那么，调用此接口不生效。
• 如果调用此接口之后的 2s 内，没有可带 SEI 的视频帧（比如没有开启视频采集和传输），那么，SEI 数据不会被加进视频帧中。
• 消息发送成功后，远端会收到 onSEIMessageReceived 回调。

setBusinessId

public abstract int com.ss.bytertc.engine.RTCEngine.setBusinessId(
    String businessId)

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

传入参数

返回值

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

注意

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

setEncryptInfo

public abstract void com.ss.bytertc.engine.RTCEngine.setEncryptInfo(
    int aesType,
    String key)

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

传入参数

注意

• 该方法与 setCustomizeEncryptHandler 为互斥关系, 即按照调用顺序，最后一个调用的方法为最终生效的版本。

• 该方法必须在调用 joinRoom 之前调用，可重复调用，以最后调用的参数作为生效参数

• AES加密算法限制，超过36位的key会被截断，仅取前36位

setCustomizeEncryptHandler

public abstract void com.ss.bytertc.engine.RTCEngine.setCustomizeEncryptHandler(
    RTCEncryptHandler handler)

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

传入参数

注意

• 该方法与 setEncryptInfo 为互斥关系，即按照调用顺序，最后一个调用的方法为最终生效的版本
• 该方法必须在调用 joinRoom 之前调用，可重复调用，以最后调用的参数作为生效参数

• 无论加密或者解密，其对原始数据的长度修改，需要控制在90%-120%之间，即如果输入数据为100字节，则处理完成后的数据必须在 90至120自己之间，如果加密或解密结果超出该长度限制，则该音视频帧会被丢弃

• 数据加密/解密为串行执行，因而视实现方式不同，可能会影响到最终渲染效率，是否使用该方法，需要由使用方谨慎评估

checkVideoEffectLicense

public abstract int com.ss.bytertc.engine.RTCEngine.checkVideoEffectLicense(
    Context context,
    String licenseFile)

视频特效许可证检查

传入参数

返回值

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

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

initVirtualBackground

public abstract int com.ss.bytertc.engine.RTCEngine.initVirtualBackground(
    Context context,
    String licenseFile,
    String modelFile)

虚拟背景功能初始化。

传入参数

返回值

• 0: 调用成功。
• 1000: 调用失败，未集成 CV SDK 。
• 1001: 调用失败，本 SDK 版本不支持 CV 功能。
• > 40000: 调用失败，CV SDK 授权错误，具体错误码请参考 CV SDK 文档。
• < 0: 调用失败，CV SDK 内部错误，具体错误码请参考 CV SDK 文档。

enableVirtualBackground

public abstract int com.ss.bytertc.engine.RTCEngine.enableVirtualBackground(
    VirtualBackgroundSource source)

开启虚拟背景。

传入参数

返回值

• 0: 调用成功。
• < 0: 调用失败，CV SDK 内部错误，具体错误码请参考 CV SDK 文档。
• -1: 调用失败，未调用 initVirtualBackground 或调用失败，导致 license 验证失败。
• -4: 调用失败，自定义背景图片打开失败。
• -37: 调用失败，自定义背景图片解码失败。
• -38: 调用失败，图片格式不支持。支持的图片格式是 jpg、jpeg、和 png。

注意

• 调用此接口前，需要先调用 initVirtualBackground 初始化 CV 环境；
• 虚拟背景仅支持摄像头采集的视频流，包括 RTC SDK 内部机制采集的方式和自定义采集的方式。虚拟背景不支持屏幕视频流。

disableVirtualBackground

public abstract int com.ss.bytertc.engine.RTCEngine.disableVirtualBackground()

关闭虚拟背景。

返回值

• 0: 调用成功。
• < 0: 调用失败，具体错误码请参考 CV SDK 文档。

注意 调用 enableVirtualBackground 开启虚拟背景后，可以调用此接口关闭虚拟背景。

setVideoEffectAlgoModelPath

public abstract void com.ss.bytertc.engine.RTCEngine.setVideoEffectAlgoModelPath(
    String modelPath)

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

传入参数

enableVideoEffect

public abstract int com.ss.bytertc.engine.RTCEngine.enableVideoEffect(
    boolean enable)

创建/销毁视频特效引擎

传入参数

返回值 方法调用结果

• 0: 成功
• !0: 失败

注意

• 该方法须在调用 checkVideoEffectLicense 和 setVideoEffectAlgoModelPath 后调用。
• 该方法不直接开启/关闭视频特效，你须在调用该方法后，调用 setVideoEffectNodes 开启视频特效。
• 通用场景下，特效引擎会随 RTC 引擎销毁而销毁。当你对性能有较高要求时，可在不使用特效相关功能时调用该方法中 false 单独销毁特效引擎。

setVideoEffectNodes

public abstract int com.ss.bytertc.engine.RTCEngine.setVideoEffectNodes(
    List<String> effectNodes)

设置视频特效素材包

传入参数

返回值

• 0: 调用成功
• 1000: 未集成 CV SDK
• 1001: 本 RTC 版本不支持 CV 功能
• < 0: 调用失败，具体错误码，请参考 CV SDK 文档。

注意 你须在调用 enableVideoEffect 后调用该方法。

updateVideoEffectNode

public abstract int com.ss.bytertc.engine.RTCEngine.updateVideoEffectNode(
    String effectNode,
    String key,
    float value)

设置特效强度

传入参数

返回值

• 0: 调用成功
• 1000: 未集成 CV SDK
• 1001: 本 RTC 版本不支持 CV 功能
• < 0: 调用失败，具体错误码，请参考 CV SDK 文档。

注意 该接口仅适用于同时含有上述三个参数的特效资源，对于如大部分贴纸类等没有强度参数的特效，该接口调用无效。

setVideoEffectColorFilter

public abstract int com.ss.bytertc.engine.RTCEngine.setVideoEffectColorFilter(
    String resFile)

设置颜色滤镜

传入参数

返回值

• 0: 调用成功
• 1000: 未集成 CV SDK
• 1001: 本 RTC 版本不支持 CV 功能
• < 0: 调用失败，具体错误码，请参考CV SDK文档。

setVideoEffectColorFilterIntensity

public abstract int com.ss.bytertc.engine.RTCEngine.setVideoEffectColorFilterIntensity(
    float intensity)

设置已启用的颜色滤镜强度

传入参数

返回值

• 0: 调用成功
• 1000: 未集成 CV SDK
• 1001: 本 RTC 版本不支持 CV 功能
• < 0: 调用失败，具体错误码，请参考 CV SDK 文档。

startCloudRendering

public abstract void com.ss.bytertc.engine.RTCEngine.startCloudRendering(
    String effectInfo)

开启云端渲染

传入参数

updateCloudRendering

public abstract void com.ss.bytertc.engine.RTCEngine.updateCloudRendering(
    String effectInfo)

更新云端渲染参数

传入参数

stopCloudRendering

public abstract void com.ss.bytertc.engine.RTCEngine.stopCloudRendering()

关闭云端渲染

setRuntimeParameters

public abstract void com.ss.bytertc.engine.RTCEngine.setRuntimeParameters(
    JSONObject params)

设置运行时的参数

feedback

public abstract int com.ss.bytertc.engine.RTCEngine.feedback(
    List<ProblemFeedback> types,
    String problemDesc)

通话结束，将用户反馈的问题上报到 RTC

传入参数

返回值

• 0: 上报成功
• -1: 上报失败，还没加入过房间
• -2: 上报失败，数据解析错误
• -3: 上报失败，字段缺失

注意 如果用户上报时在房间内，那么问题会定位到用户当前所在的一个或多个房间；如果用户上报时不在房间内，那么问题会定位到引擎此前退出的房间。

startASR

public abstract void com.ss.bytertc.engine.RTCEngine.startASR(
    RTCASRConfig asrConfig,
    IRTCASREngineEventHandler handler)

开启自动语音识别服务。该方法将识别后的用户语音转化成文字，并通过 onMessage 事件回调给用户。

传入参数

stopASR

public abstract void com.ss.bytertc.engine.RTCEngine.stopASR()

关闭语音识别服务

startFileRecording

public abstract int com.ss.bytertc.engine.RTCEngine.startFileRecording(
    StreamIndex type,
    RecordingConfig config)

该方法将通话过程中的音视频数据录制到本地的文件中。

传入参数

返回值 0: 正常

-1: 参数设置异常 -2: 当前版本 SDK 不支持该特性，请联系技术支持人员

注意

• 调用该方法后，你会收到 onRecordingStateUpdate 回调。
• 如果录制正常，系统每秒钟会通过 onRecordingProgressUpdate 回调通知录制进度。

stopFileRecording

public abstract void com.ss.bytertc.engine.RTCEngine.stopFileRecording(
    StreamIndex type)

停止本地录制

传入参数

注意

• 调用 startFileRecording 开启本地录制后，你必须调用该方法停止录制。
• 调用该方法后，你会收到 onRecordingStateUpdate 回调提示录制结果。

getAudioMixingManager

public abstract IAudioMixingManager com.ss.bytertc.engine.RTCEngine.getAudioMixingManager()

混音管理接口创建

返回值 混音管理实例，详见IAudioMixingManager

getPositionAudioRender

public abstract IPositionAudioRender com.ss.bytertc.engine.RTCEngine.getPositionAudioRender()

获取位置音频接口实例，包括范围语音、空间语音等和位置相关的音频接口。

返回值 位置音频管理接口实例。如果返回 NULL，则表示不支持空间音频，详见 IPositionAudioRender 。

注意

• 只有在使用支持真双声道播放的设备时，才能开启空间音频效果；
• 在网络状况不佳的情况下，即使开启了这一功能，也不会产生空间音频效果；
• 机型性能不足可能会导致音频卡顿，使用低端机时，不建议开启空间音频效果；
• 空间音频效果在启用服务端选路功能时，不生效。

setScreenAudioSourceType

public abstract void com.ss.bytertc.engine.RTCEngine.setScreenAudioSourceType(
    AudioSourceType sourceType)

在屏幕共享时，设置屏幕音频的采集方式（内部采集/自定义采集）

传入参数

注意

• 默认采集方式是 RTC SDK 内部采集。当前不支持使用内部采集，请调用此方法，设置为使用自定义采集。
• 你应该在 publishScreen 前，调用此方法。否则，你将收到 onWarning 的报错：WARNING_CODE_SET_SCREEN_AUDIO_SOURCE_TYPE_FAILED
• 如果设定为自定义采集，你必须再调用 pushScreenAudioFrame 将自定义采集到的屏幕音频帧推送到 RTC SDK。
• 无论是内部采集还是自定义采集，你都必须调用 publishScreen 将采集到的屏幕音频推送到远端。

setScreenAudioStreamIndex

public abstract void com.ss.bytertc.engine.RTCEngine.setScreenAudioStreamIndex(
    StreamIndex index)

在屏幕共享时，设置屏幕音频流和麦克风采集到的音频流的混流方式

传入参数

注意 你应该在 publishScreen 之前，调用此方法。否则，你将收到 onWarning 的报错：WARNING_CODE_SET_SCREEN_STREAM_INDEX_FAILED

pushScreenAudioFrame

public abstract int com.ss.bytertc.engine.RTCEngine.pushScreenAudioFrame(
    AudioFrame audioFrame)

使用自定义采集方式，采集屏幕共享时的屏幕音频时，将音频帧推送至 RTC SDK 处进行编码等处理。

传入参数

返回值 方法调用结果

• 0: 设置成功
• < 0: 设置失败

注意

• 调用此接口推送屏幕共享时的自定义采集的音频数据前，必须调用 setScreenAudioSourceType 开启屏幕音频自定义采集。
• 你应每隔 10 毫秒，调用一次此方法推送一次自定义采集的音频帧。一次推送的音频帧中应包含 frame.sample_rate / 100 个音频采样点。比如，假如采样率为 48000Hz，则每次应该推送 480 个采样点。
• 音频采样格式为 S16。音频缓冲区内的数据格式必须为 PCM 数据，其容量大小应该为 samples
• 此函数运行在用户级线程内。若同时运行其他进程，将导致本进程中断。
• 调用此接口将自定义采集的音频帧推送到 RTC SDK 后，你必须调用 publishScreen 将采集到的屏幕音频推送到远端。在调用 publishScreen 前，推送到 RTC SDK 的音频帧信息会丢失。

setExternalVideoEncoderEventHandler

public abstract void com.ss.bytertc.engine.RTCEngine.setExternalVideoEncoderEventHandler(
    IExternalVideoEncoderEventHandler encoder_handler)

注册自定义编码帧推送事件回调

传入参数

注意

• 该方法需在进房前调用。
• 引擎销毁前需取消注册，调用该方法将参数设置为 nullptr 即可。

pushExternalEncodedVideoFrame

public abstract boolean com.ss.bytertc.engine.RTCEngine.pushExternalEncodedVideoFrame(
    StreamIndex index,
    int video_index,
    RTCEncodedVideoFrame video_stream)

推送自定义编码后的视频流

传入参数

注意

• 目前仅支持推送 H264 和 ByteVC1 格式的视频帧。
• 该函数运行在用户调用线程内
• 推送自定义编码视频帧前，必须调用 setVideoSourceType 将视频输入源切换至自定义编码视频源。

setVideoDecoderConfig

public abstract void com.ss.bytertc.engine.RTCEngine.setVideoDecoderConfig(
    RemoteStreamKey key,
    VideoDecoderConfig config)

在订阅远端视频流之前，设置远端视频数据解码方式

传入参数

注意

• 该方法近适用于手动订阅模式，并且在订阅远端流之前使用。
• 当你想要对远端流进行自定义解码时，你需要先调用 registerRemoteEncodedVideoFrameObserver 注册远端视频流监测器，然后再调用该接口将解码方式设置为自定义解码。监测到的视频数据会通过 OnRemoteEncodedVideoFrame 回调出来。

requestRemoteVideoKeyFrame

public abstract void com.ss.bytertc.engine.RTCEngine.requestRemoteVideoKeyFrame(
    RemoteStreamKey stream_info)

在订阅远端视频流之后，向远端请求关键帧

传入参数

注意

• 该方法仅适用于手动订阅模式，并且在成功订阅远端流之后使用。
• 该方法适用于调用 setVideoDecoderConfig 开启自定义解码功能后，并且自定义解码失败的情况下使用

registerRemoteEncodedVideoFrameObserver

public abstract void com.ss.bytertc.engine.RTCEngine.registerRemoteEncodedVideoFrameObserver(
    IRemoteEncodedVideoFrameObserver observer)

注册远端编码后视频数据回調。
完成注册后，当 SDK 监测到远端编码后视频帧时，会触发 OnRemoteEncodedVideoFrame 回调

传入参数

注意

• 该方法需在进房前调用。
• 引擎销毁前需取消注册，调用该方法将参数设置为 nullptr 即可。

setEarMonitorMode

public abstract void com.ss.bytertc.engine.RTCEngine.setEarMonitorMode(
    EarMonitorMode mode)

打开/关闭耳返功能。

传入参数

注意

• 你必须在使用 RTC SDK 提供的内部音频采集功能时，使用耳返功能。
• 耳返功能仅在连接了有线耳机时有效。
• RTC SDK 支持硬件耳返和软件耳返。一般来说，硬件耳返的时延和音质等效果明显更佳。 关于你的应用能否使用硬件耳返功能，你需要联系终端厂商进行确认和开启白名单。此后，你必须联系技术支持同学，在 RTC 侧开启硬件耳返白名单。

setEarMonitorVolume

public abstract void com.ss.bytertc.engine.RTCEngine.setEarMonitorVolume(
    int volume)

设置耳返音量。

传入参数

注意

• 设置耳返音量前，你必须先调用 setEarMonitorMode 打开耳返功能。
• 耳返功能仅在使用 RTC SDK 提供的内部音频采集功能，并连接了有线耳机时有效。

enableAudioPropertiesReport

public abstract void com.ss.bytertc.engine.RTCEngine.enableAudioPropertiesReport(
    AudioPropertiesConfig config)

启用音频信息提示。

传入参数

注意 开启提示后，你可以： + 通过 onLocalAudioPropertiesReport 回调获取本地麦克风和屏幕音频流采集的音频信息；

• 通过 onRemoteAudioPropertiesReport 回调获取订阅的远端用户的音频信息。

sendStreamSyncInfo

public abstract int com.ss.bytertc.engine.RTCEngine.sendStreamSyncInfo(
    byte[] data,
    StreamSycnInfoConfig config)

发送音频流同步信息。将消息通过音频流发送到远端，并实现与音频流同步，该接口调用成功后，远端用户会收到 onStreamSyncInfoReceived 回调。

传入参数

返回值

• >=0: 消息发送成功。返回成功发送的次数。
• -1: 消息发送失败。消息长度大于 16 字节。
• -2: 消息发送失败。传入的消息内容为空。
• -3: 消息发送失败。通过屏幕流进行消息同步时，此屏幕流还未发布。
• -4: 消息发送失败。通过用麦克风或自定义设备采集到的音频流进行消息同步时，此音频流还未发布，详见错误码 ErrorCode。

isCameraTorchSupported

public abstract boolean com.ss.bytertc.engine.RTCEngine.isCameraTorchSupported()

检测当前使用的摄像头（前置/后置），是否支持闪光灯。

返回值

• true: 支持
• false: 不支持

注意 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能检测闪光能力。

isCameraZoomSupported

public abstract boolean com.ss.bytertc.engine.RTCEngine.isCameraZoomSupported()

检测当前使用的摄像头（前置/后置），是否支持变焦（数码/光学变焦）。

返回值

• true: 支持
• false: 不支持

注意 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能检测摄像头变焦能力。

setCameraZoomRatio

public abstract int com.ss.bytertc.engine.RTCEngine.setCameraZoomRatio(
    float zoom)

设置当前使用的摄像头（前置/后置）的变焦倍数

传入参数

返回值

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

注意

• 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能设置摄像头变焦倍数。
• 设置结果在调用 stopVideoCapture 关闭内部采集后失效。

getCameraZoomMaxRatio

public abstract float com.ss.bytertc.engine.RTCEngine.getCameraZoomMaxRatio()

获取当前使用的摄像头（前置/后置）的最大变焦倍数

返回值 最大变焦倍数

注意 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能检测摄像头最大变焦倍数。

setCameraTorch

public abstract int com.ss.bytertc.engine.RTCEngine.setCameraTorch(
    TorchState torch_state)

打开/关闭当前使用的摄像头（前置/后置）的闪光灯

传入参数

返回值

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

注意

• 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能设置闪光灯。
• 设置结果在调用 stopVideoCapture 关闭内部采集后失效。

startForwardStreamToRooms

public abstract int com.ss.bytertc.engine.RTCEngine.startForwardStreamToRooms(
    List<ForwardStreamInfo> forwardStreamInfos)

开始跨房间转发媒体流。 在用户进入房间后调用本接口，实现向多个房间转发媒体流，适用于跨房间连麦等场景。

传入参数

返回值

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

注意

• 调用本方法后，将在本端触发 onForwardStreamStateChanged 回调。
• 调用本方法后，你可以通过监听 onForwardStreamEvent 回调来获取各个目标房间在转发媒体流过程中的相关事件。
• 开始转发后，目标房间中的用户将接收到本地用户进房 onUserJoined 和发流 onStreamAdd 的回调。
• 调用本方法后，可以调用 updateForwardStreamToRooms 更新目标房间信息，例如，增加或减少目标房间等。
• 调用本方法后，可以调用 stopForwardStreamToRooms 停止向所有房间转发媒体流。
• 调用本方法后，可以调用 pauseForwardStreamToAllRooms 暂停向所有房间转发媒体流。

updateForwardStreamToRooms

public abstract int com.ss.bytertc.engine.RTCEngine.updateForwardStreamToRooms(
    List<ForwardStreamInfo> forwardStreamInfos)

更新跨房间媒体流转发信息。
通过 startForwardStreamToRooms 发起媒体流转发后，可调用本方法增加或者减少目标房间，或更新房间密钥。 调用本方法增加或删减房间后，将在本端触发 onForwarStreamStateChangedonForwardStreamStateChanged 回调，包含发生了变动的目标房间中媒体流转发状态。

传入参数

返回值

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

注意

• 增加目标房间后，新增目标房间中的用户将接收到本地用户进房 onUserJoined 和发布 onStreamAdd 的回调。
• 删减目标房间后，原目标房间中的用户将接收到本地用户停止发布 onStreamRemove 和退房 onUserLeave 的回调。

stopForwardStreamToRooms

public abstract void com.ss.bytertc.engine.RTCEngine.stopForwardStreamToRooms()

停止跨房间媒体流转发。 通过 startForwardStreamToRooms 发起媒体流转发后，可调用本方法停止向所有目标房间转发媒体流。

注意

• 调用本方法后，将在本端触发 onForwardStreamStateChanged 回调。
• 调用本方法后，原目标房间中的用户将接收到本地用户停止发布 onStreamRemove 和退房 onUserLeave 的回调。
• 如果需要停止向指定的房间转发媒体流，请调用 updateForwardStreamToRooms 更新房间信息。
• 如果需要暂停转发，请调用 pauseForwardStreamToAllRooms，并在之后随时调用 resumeForwardStreamToAllRooms 快速恢复转发。

pauseForwardStreamToAllRooms

public abstract void com.ss.bytertc.engine.RTCEngine.pauseForwardStreamToAllRooms()

暂停跨房间媒体流转发。 通过 startForwardStreamToRooms 发起媒体流转发后，可调用本方法暂停向所有目标房间转发媒体流。 调用本方法暂停向所有目标房间转发后，你可以随时调用 resumeForwardStreamToAllRooms 快速恢复转发。

注意 调用本方法后，目标房间中的用户将接收到本地用户停止发布 onStreamRemove 和退房 onUserLeave 的回调。

resumeForwardStreamToAllRooms

public abstract void com.ss.bytertc.engine.RTCEngine.resumeForwardStreamToAllRooms()

恢复跨房间媒体流转发。 调用 pauseForwardStreamToAllRooms 暂停转发之后，调用本方法恢复向所有目标房间转发媒体流。

注意 目标房间中的用户将接收到本地用户进房 onUserJoined 和发布 onStreamAdd 的回调。

IAudioMixingManager

public abstract class com.ss.bytertc.engine.audio.IAudioMixingManager

混音管理类

成员函数

函数说明

startAudioMixing

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.startAudioMixing(
    int mixId,
    String filePath,
    AudioMixingConfig config)

开始播放音频文件。
可以通过传入不同的 ID 和 filepath 多次调用本方法，以实现同时播放多个混音文件，实现混音叠加。

传入参数

注意

• 如果已经通过 preloadAudioMixing 将音效加载至内存，确保此处的 ID 与 preloadAudioMixing 设置的 ID 相同。
• 调用本方法播放音频文件后，关于当前的混音状态，会收到回调 onAudioMixingStateChanged。
• 开始播放音频文件后，可以调用 stopAudioMixing 方法停止播放音频文件。
• 本方法的混音数据来源于外部文件，而 enableAudioMixingFrame 的混音数据来源于外部缓存且音频格式为 PCM，这两种混音方式可以共存。

stopAudioMixing

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.stopAudioMixing(
    int mixId)

停止播放音频文件

传入参数

注意

• 调用 startAudioMixing 方法开始播放音频文件后，可以调用本方法停止播放音频文件。
• 调用本方法停止播放音频文件后，关于当前的混音状态，会收到回调 onAudioMixingStateChanged。
• 调用本方法停止播放音频文件后，该音频文件会被自动卸载。

pauseAudioMixing

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.pauseAudioMixing(
    int mixId)

暂停播放音频文件

传入参数

注意

• 调用 startAudioMixing 方法开始播放音频文件后，可以通过调用本方法暂停播放音频文件。
• 调用本方法暂停播放音频文件后，可调用 resumeAudioMixing 方法恢复播放及混音。
• 调用本方法暂停播放音频文件后，关于当前的混音状态，会收到回调 onAudioMixingStateChanged。

resumeAudioMixing

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.resumeAudioMixing(
    int mixId)

恢复播放音频文件

传入参数

注意

• 调用 pauseAudioMixing 方法暂停播放音频文件后，可以通过调用本方法恢复播放及混音。
• 调用本方法恢复播放音频文件后，关于当前的混音状态，会收到回调 onAudioMixingStateChanged。

preloadAudioMixing

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.preloadAudioMixing(
    int mixId,
    String filePath)

预加载指定音频文件到内存中

传入参数

注意

• 需要频繁播放某个音频文件的时候，调用本方法预加载该文件，在播放的时候可以只加载一次该文件，减少 CPU 占用。
• 本方法只是预加载指定音频文件，只有调用 startAudioMixing 方法才开始播放指定音频文件。
• 调用本方法预加载音频文件后，关于当前的混音状态，会收到回调 onAudioMixingStateChanged。
• 调用本方法预加载的指定音频文件可以通过 unloadAudioMixing 卸载。

unloadAudioMixing

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.unloadAudioMixing(
    int mixId)

卸载指定音频文件

传入参数

注意 调用本方法卸载该文件后，关于当前的混音状态，会收到回调 onAudioMixingStateChanged。

setAudioMixingVolume

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.setAudioMixingVolume(
    int mixId,
    int volume,
    AudioMixingType type)

调节混音的音量大小，包括音频文件混音和 PCM 混音。

传入参数

getAudioMixingDuration

public abstract int com.ss.bytertc.engine.audio.IAudioMixingManager.getAudioMixingDuration(
    int mixId)

获取音频文件时长

传入参数

返回值

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

注意 调用本方法获取音频文件时长前，需要先调用 preloadAudioMixing 或 startAudioMixing。

getAudioMixingCurrentPosition

public abstract int com.ss.bytertc.engine.audio.IAudioMixingManager.getAudioMixingCurrentPosition(
    int mixId)

获取音频文件播放进度

传入参数

返回值

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

注意 调用本方法获取音频文件播放进度前，需要先调用 startAudioMixing 开始播放音频文件。

setAudioMixingPosition

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.setAudioMixingPosition(
    int mixId,
    int position)

设置音频文件的起始播放位置

传入参数

注意

• 调用本方法你可以根据实际情况从指定的位置播放音频文件，无需从头到尾完整播放一个音频文件。
• 调用本方法设置音频文件起始播放位置前，需要先调用 startAudioMixing 开始播放音频文件。

setAudioMixingDualMonoMode

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.setAudioMixingDualMonoMode(
    int mixId,
    AudioMixingDualMonoMode mode)

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

传入参数

注意

• 调用本方法设置音频文件的声道模式前，需要先调用 startAudioMixing 开始播放音频文件。
• 此方法对 enableAudioMixingFrame 播放的音乐无效。

setAudioMixingPitch

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.setAudioMixingPitch(
    int mixId,
    int pitch)

开启本地播放音乐文件变调功能，多用于 K 歌场景。
使用该方法，你可以对本地播放音乐文件的音调进行升调或降调等调整。

传入参数

注意 本方法需要在调用 startAudioMixing 开始播放音频文件后、调用 stopAudioMixing 停止播放音频文件前使用，否则会触发 onAudioMixingStateChanged 回调报错

setAudioMixingProgressInterval

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.setAudioMixingProgressInterval(
    int mixId,
    long interval)

设置混音时音频文件播放进度回调的间隔

传入参数

注意 本方法需要在调用 startAudioMixing 开始播放音频文件后、调用 stopAudioMixing 停止播放音频文件前使用，否则会触发 onAudioMixingStateChanged 回调报错。 若想在音乐文件开始播放前设置播放进度回调间隔，你需调用 startAudioMixing 在 AudioMixingConfig 中设置时间间隔，开始播放后可以通过此接口更新回调间隔。

enableAudioMixingFrame

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.enableAudioMixingFrame(
    int mixId,
    AudioMixingType type)

启动 PCM 音频数据混音

传入参数

注意

• 必须先调用本方法启动 PCM 音频数据混音，随后调用 pushAudioMixingFrame 方法，才会开始混音。
• 如要结束 PCM 音频数据混音，使用 disableAudioMixingFrame。

disableAudioMixingFrame

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.disableAudioMixingFrame(
    int mixId)

关闭 PCM 混音

传入参数

pushAudioMixingFrame

public abstract int com.ss.bytertc.engine.audio.IAudioMixingManager.pushAudioMixingFrame(
    int mixId,
    AudioFrame audioFrame)

推送 PCM 音频帧数据用于混音

传入参数

返回值

• 0: 成功
• < 0: 失败

注意

• 调用该方法前，须通过 enableAudioMixingFrame 启动外部音频流混音。
• 使用参考建议：首次推送数据，请在应用侧先缓存一定数据（如 200 毫秒），然后一次性推送过去；此后的推送操作定时 10 毫秒一次，并且每次的音频数据量为 10 毫秒数据量。要暂停播放，暂停推送即可。

getAudioTrackCount

public abstract int com.ss.bytertc.engine.audio.IAudioMixingManager.getAudioTrackCount(
    int mixId)

获取当前音频文件的音轨索引

传入参数

返回值 方法调用结果

• ≥ 0：成功，返回当前音频文件的音轨索引
• < 0：方法调用失败

注意

• 调用本方法获取音频文件的音轨前，需要先调用 startAudioMixing 开始播放音频文件。
• 此方法对 enableAudioMixingFrame 播放的音频无效。

selectAudioTrack

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.selectAudioTrack(
    int mixId,
    int audioTrackIndex)

指定当前音频文件的播放音轨

传入参数

注意

• 调用本方法设置音频文件的音轨前，需要先调用 startAudioMixing 开始播放音频文件。
• 此方法对 enableAudioMixingFrame 播放的音乐无效。

IPositionAudioRender

public interface com.ss.bytertc.engine.audio.IPositionAudioRender

位置音频接口

成员函数

函数说明

enableAudioSpatialRender

void com.ss.bytertc.engine.audio.IPositionAudioRender.enableAudioSpatialRender(
    boolean enable)

开启或关闭空间音频效果。

传入参数

updatePosition

int com.ss.bytertc.engine.audio.IPositionAudioRender.updatePosition(
    Position pos)

更新自己的位置坐标。

传入参数

返回值

• 0: 参数检查通过，但不代表更新成功；
• 其他: 更新失败。

updateSelfOrientation

int com.ss.bytertc.engine.audio.IPositionAudioRender.updateSelfOrientation(
    HumanOrientation orientation)

更新自己的朝向。本地朝向的设置只影响本地听到的音频效果，不影响本地发出的音频效果。

传入参数

返回值 0: 代表更新成功

注意 本地用户调用 enableAudioSpatialRender 使用空间音频功能时，需要调用 updatePosition 接口更新位置坐标后，才能调用此接口。

IVideoProcessor

public abstract class com.ss.bytertc.engine.video.IVideoProcessor

成员函数

函数说明

processVideoFrame

public abstract VideoFrame com.ss.bytertc.engine.video.IVideoProcessor.processVideoFrame(
    VideoFrame frame)

获取 RTC SDK 采集得到的视频帧，根据 registerLocalVideoProcessor 设置的视频前处理器，进行视频前处理，最终将处理后的视频帧给到 RTC SDK 用于编码传输。

传入参数

返回值 经过视频前处理后的视频帧，返回给 RTC SDK 供编码和传输，参看 VideoFrame。

注意

• 如果你使用此接口所在线程进行视频前处理，你无需设置 OpenGL 环境；如果你选择使用其他线程，必须设置 OpenGL 环境。
• 使用自定义视频滤镜返回的视频数据，构建返回给 RTC SDK 的视频帧时，根据返回视频数据格式的不同，需要不同的处理：
• 返回的视频数据是纹理格式时，可以使用 GLTextureVideoFrameBuilder 创建返回帧；
• 返回的视频数据是 I420 格式时，可以使用 CpuBufferVideoFrameBuilder 创建返回帧。
• 若在构造返回的视频帧时，设置了资源释放回调（详见 VideoFrame 的构造函数），那么 RTC SDK 会复用该视频帧，所以在回调被调用之前，不要对资源进行操作以避免冲突。
• 在进行视频前处理前，你需要调用 registerLocalVideoProcessor 设置视频前处理器。
• 如果需要取消视频前处理，可以将视频前处理器设置为 nullptr。

onGLEnvInitiated

public void com.ss.bytertc.engine.video.IVideoProcessor.onGLEnvInitiated()

OpenGL 环境创建完成时，收到此回调。

注意 当你选择使用 processVideoFrame 所在线程以外的线程进行视频前处理时，必须设置 OpenGL 环境。环境创建完成时，你会收到此通知，此时，你可以进行一些初始化操作。

onGLEnvRelease

public void com.ss.bytertc.engine.video.IVideoProcessor.onGLEnvRelease()

OpenGL 环境即将销毁时，收到此回调。此时，你可以释放纹理等资源。

IRTCRoom

public abstract class com.ss.bytertc.engine.IRTCRoom

成员函数

函数说明

destroy

public abstract void com.ss.bytertc.engine.IRTCRoom.destroy()

销毁房间

joinRoom

public abstract int com.ss.bytertc.engine.IRTCRoom.joinRoom(
    String token,
    UserInfo userInfo,
    MultiRoomConfig roomConfig)

加入房间。
多房间场景下，调用 createRoom 创建房间后，调用此方法加入房间，同房间内其他用户进行音视频通话。

传入参数

返回值

• 0：方法调用成功。
• -1：roomID / userInfo.uid 包含了无效的参数。
• -2：已经在房间内。接口调用成功后，只要收到返回值为 0 ，且未调用 leaveRoom 成功，则再次调用进房接口时，无论填写的房间 ID 和用户 ID 是否重复，均触发此返回值。
• -3：room 为空。

注意

• 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后进房的用户会将先进房的用户踢出房间，并且先进房的用户会收到 onError 回调通知，错误类型详见 ErrorCode 中的 kErrorCodeDuplicateLogin。
• 本地用户调用此方法加入房间成功后，会收到 onJoinRoomResult 回调通知。
• 本地用户调用 setUserVisibility 将自身设为可见后加入房间，远端用户会收到 onUserJoined 回调通知。
• 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本地会收到 onJoinRoomResult 回调通知；如果加入房间的用户是主播角色，远端用户会收到 onUserJoined 回调通知。

setRTCRoomEventHandler

public abstract void com.ss.bytertc.engine.IRTCRoom.setRTCRoomEventHandler(
    IRTCRoomEventHandler rtcRoomEventHandler)

设置房间事件回调 handler

传入参数

leaveRoom

public abstract void com.ss.bytertc.engine.IRTCRoom.leaveRoom()

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

注意

• 调用 setUserVisibility 将自身设为可见的用户离开房间后，房间内其他用户会收到 onUserLeave 回调通知。
• 如果调用此方法后立即销毁引擎，SDK 将无法触发 onLeaveRoom 回调。

setUserVisibility

public abstract void com.ss.bytertc.engine.IRTCRoom.setUserVisibility(
    boolean enable)

设置用户可见性。默认可见。
通过设置用户的可见性，可以控制用户在房间内的行为：

• 能否发布音视频流；
  
• 用户自身是否在房间中隐身。
  

传入参数

返回值

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

注意

• 在加入房间前后，用户均可调用此方法设置用户可见性。
• 在房间内，调用此方法成功切换用户可见性后，房间内其他用户会收到相应的回调通知：
• 从可见换至不可见时，房间内其他用户会收到 onUserJoined；
• 从不可见切换至可见时，房间内其他用户会收到 onUserLeave 。

updateToken

public abstract void com.ss.bytertc.engine.IRTCRoom.updateToken(
    String token)

更新 Token。
用于加入房间的 Token 有一定的有效期。当 Token 过期时，需要调用此方法更新房间的 Token 信息。
调用 joinRoom 方法加入房间或断网重连进入房间时，如果 Token 过期，将导致加入房间失败，并会收到 onError 回调通知，回调错误码为 ErrorCode 中的 ERROR_CODE_INVALID_TOKEN。此时需要重新获取 Token，并调用此方法更新 Token。

传入参数

注意

• 如果因 Token 过期导致加入房间失败，则调用此方法更新 Token 后，SDK 会自动重新加入房间，不需要再次调用 joinRoom 方法。
• Token 过期时，如果已经加入房间成功，则不会受到影响。

sendUserMessage

public abstract void com.ss.bytertc.engine.IRTCRoom.sendUserMessage(
    String userId,
    String messageStr)

给房间内指定的用户发送点对点文本消息

传入参数

注意

• 在发送房间内文本消息前，必须先调用 joinRoom 加入房间。
• 调用后，会收到 onUserMessageSendResult 回调，通知消息发送成功或失败；
• 若消息发送成功，则 userId 所指定的用户会收到 onUserMessageReceived 回调。

sendUserBinaryMessage

public abstract void com.ss.bytertc.engine.IRTCRoom.sendUserBinaryMessage(
    String userId,
    byte[] buffer)

给房间内指定的用户发送点对点二进制消息。

传入参数

注意

• 在发送房间内二进制消息前，必须先调用 joinRoom 加入房间。
• 调用后，会收到 onUserMessageSendResult 回调，通知消息发送成功或失败；
• 若消息发送成功，则 userId 所指定的用户会收到 onUserBinaryMessageReceived 回调。

sendRoomMessage

public abstract void com.ss.bytertc.engine.IRTCRoom.sendRoomMessage(
    String messageStr)

给房间内的所有其他用户群发文本消息。

传入参数

注意

• 在房间内广播文本消息前，必须先调用 joinRoom 加入房间。
• 调用后，会收到 onRoomMessageSendResult 回调；
• 同一房间内的其他用户会收到 onRoomMessageReceived 回调。

sendRoomBinaryMessage

public abstract void com.ss.bytertc.engine.IRTCRoom.sendRoomBinaryMessage(
    byte[] buffer)

给房间内的所有其他用户群发二进制消息。

传入参数

注意

• 在房间内广播二进制消息前，必须先调用 joinRoom 加入房间。
• 调用后，会收到 onRoomMessageSendResult 回调；
• 同一房间内的其他用户会收到 onRoomBinaryMessageReceived 回调。

publish

public abstract void com.ss.bytertc.engine.IRTCRoom.publish()

发布本地视频流。

注意 1.多房间模式下，默认音视频流不自动发布。你必须调用此接口，进行手动发布。 2.调用 setUserVisibility 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布音视频流。 3.用户在房间内，同一时间仅能在一个房间内发布音视频流。 4.用户调用此方法成功发布音视频流后，房间中的其他用户将会收到 onStreamAdd 回调通知。

unpublish

public abstract void com.ss.bytertc.engine.IRTCRoom.unpublish()

取消发布本地视频流。

注意

• 在多房间模式下，调用 publish 手动发布音视频流后，调用此接口停止发布。
• 用户调用此方法停止发布音视频流后，房间中的其他用户将会收到 onStreamRemove 回调通知。

publishScreen

public abstract void com.ss.bytertc.engine.IRTCRoom.publishScreen()

发布本地屏幕共享流。

注意

• 直播、游戏、云游戏房间模式下，此方法仅适用于角色为主播的用户。可以通过调用 setUserVisibility 方法，设置用户角色。
• 调用后，远端会收到 onFirstRemoteVideoFrameRendered 和 onStreamAdd 回调。
• 调用后，本地会收到 onFirstLocalVideoFrameCaptured 回调。
• 调用此方法发布本端屏幕共享流后: 1、还需要周期性调用 pushScreenFrame 方法，将共享的屏幕数据推送给 SDK。 2、或者调用 startScreenVideoCapture方法，启动SDK内部采集屏幕数据

unpublishScreen

public abstract void com.ss.bytertc.engine.IRTCRoom.unpublishScreen()

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

注意

• 使用 publishScreen 发布本地屏幕共享流后，可以调用此接口停止发布本地屏幕共享流。
• 调用后，远端会收到 onStreamRemove 回调。

subscribeUserStream

public abstract void com.ss.bytertc.engine.IRTCRoom.subscribeUserStream(
    String uid,
    StreamIndex streamType,
    RTCEngine.SubscribeMediaType mediaType,
    SubscribeVideoConfig subscribeVideoConfig)

订阅房间内指定的远端音视频流。
无论自动订阅还是手动订阅模式，用户都可以调用此方法按需订阅房间中的音视频流。
该方法也可用于更新已经订阅的流的属性、媒体类型等配置。

传入参数

注意

• 你可以通过 onStreamAdd 和 onStreamRemove 两个回调获取当前房间你的音视频流信息，并调用本方法按需订阅流或修改订阅配置。
• 若订阅失败，你会收到 onRoomError 回调通知，具体失败原因参看 ErrorCode。
• 若调用 pauseAllSubscribedStream 暂停接收远端音视频流，此时仍可使用该方法对暂停接收的流进行设置，你会在调用 resumeAllSubscribedStream 恢复接收流后收到修改设置后的流。

pauseAllSubscribedStream

public abstract void com.ss.bytertc.engine.IRTCRoom.pauseAllSubscribedStream(
    RTCEngine.PauseResumeControlMediaType mediaType)

暂停接收来自远端的媒体流。

传入参数

注意

• 该方法仅暂停远端流的接收，并不影响远端流的采集和发送；
• 该方法不改变用户的订阅状态以及订阅流的属性。
• 若想恢复接收远端流，需调用 resumeAllSubscribedStream。

resumeAllSubscribedStream

public abstract void com.ss.bytertc.engine.IRTCRoom.resumeAllSubscribedStream(
    RTCEngine.PauseResumeControlMediaType mediaType)

恢复接收来自远端的媒体流

传入参数

注意

• 该方法仅恢复远端流的接收，并不影响远端流的采集和发送；
• 该方法不改变用户的订阅状态以及订阅流的属性。

startLiveTranscoding

public abstract void com.ss.bytertc.engine.IRTCRoom.startLiveTranscoding(
    LiveTranscoding liveTranscode,
    ILiveTranscodingObserver observer)

开启转推直播，并设置合流的视频视图布局和音频属性。

传入参数

注意

• 只有房间模式为直播模式，且用户角色为主播的用户才能调用此方法。
• 调用该方法后，关于启动结果和推流过程中的错误，会受到 onStreamMixingEvent 回调。
• 调用 stopLiveTranscoding 停止转推直播。

stopLiveTranscoding

public abstract void com.ss.bytertc.engine.IRTCRoom.stopLiveTranscoding()

停止转推直播。
关于启动转推直播，参看 startLiveTranscoding。

updateLiveTranscoding

public abstract void com.ss.bytertc.engine.IRTCRoom.updateLiveTranscoding(
    LiveTranscoding transcoding)

更新转推直播参数。
使用 startLiveTranscoding 启用转推直播功能后，使用此方法更新功能配置参数。

传入参数

startForwardStreamToRooms

public abstract int com.ss.bytertc.engine.IRTCRoom.startForwardStreamToRooms(
    List<ForwardStreamInfo> forwardStreamInfos)

开始跨房间转发媒体流。 在用户进入房间后调用本接口，实现向多个房间转发媒体流，适用于跨房间连麦等场景。

传入参数

返回值

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

注意

• 调用本方法后，将在本端触发 onForwardStreamStateChanged 回调。
• 调用本方法后，你可以通过监听 onForwardStreamEvent 回调来获取各个目标房间在转发媒体流过程中的相关事件。
• 开始转发后，目标房间中的用户将接收到本地用户进房 onUserJoined 和发流 onStreamAdd 的回调。
• 调用本方法后，可以调用 updateForwardStreamToRooms 更新目标房间信息，例如，增加或减少目标房间等。
• 调用本方法后，可以调用 stopForwardStreamToRooms 停止向所有房间转发媒体流。
• 调用本方法后，可以调用 pauseForwardStreamToAllRooms 暂停向所有房间转发媒体流。

updateForwardStreamToRooms

public abstract int com.ss.bytertc.engine.IRTCRoom.updateForwardStreamToRooms(
    List<ForwardStreamInfo> forwardStreamInfos)

更新跨房间媒体流转发信息。
通过 startForwardStreamToRooms 发起媒体流转发后，可调用本方法增加或者减少目标房间，或更新房间密钥。 调用本方法增加或删减房间后，将在本端触发 onForwarStreamStateChangedonForwardStreamStateChanged 回调，包含发生了变动的目标房间中媒体流转发状态。

传入参数

返回值

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

注意

• 增加目标房间后，新增目标房间中的用户将接收到本地用户进房 onUserJoined 和发布 onStreamAdd 的回调。
• 删减目标房间后，原目标房间中的用户将接收到本地用户停止发布 onStreamRemove 和退房 onUserLeave 的回调。

stopForwardStreamToRooms

public abstract void com.ss.bytertc.engine.IRTCRoom.stopForwardStreamToRooms()

停止跨房间媒体流转发。 通过 startForwardStreamToRooms 发起媒体流转发后，可调用本方法停止向所有目标房间转发媒体流。

注意

• 调用本方法后，将在本端触发 onForwardStreamStateChanged 回调。
• 调用本方法后，原目标房间中的用户将接收到本地用户停止发布 onStreamRemove 和退房 onUserLeave 的回调。
• 如果需要停止向指定的房间转发媒体流，请调用 updateForwardStreamToRooms 更新房间信息。
• 如果需要暂停转发，请调用 pauseForwardStreamToAllRooms，并在之后随时调用 resumeForwardStreamToAllRooms 快速恢复转发。

pauseForwardStreamToAllRooms

public abstract void com.ss.bytertc.engine.IRTCRoom.pauseForwardStreamToAllRooms()

暂停跨房间媒体流转发。 通过 startForwardStreamToRooms 发起媒体流转发后，可调用本方法暂停向所有目标房间转发媒体流。 调用本方法暂停向所有目标房间转发后，你可以随时调用 resumeForwardStreamToAllRooms 快速恢复转发。

注意 调用本方法后，目标房间中的用户将接收到本地用户停止发布 onStreamRemove 和退房 onUserLeave 的回调。

resumeForwardStreamToAllRooms

public abstract void com.ss.bytertc.engine.IRTCRoom.resumeForwardStreamToAllRooms()

恢复跨房间媒体流转发。 调用 pauseForwardStreamToAllRooms 暂停转发之后，调用本方法恢复向所有目标房间转发媒体流。

注意 目标房间中的用户将接收到本地用户进房 onUserJoined 和发布 onStreamAdd 的回调。