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,
    JSONObject parameters)

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

传入参数

返回值

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

注意

• 如果你在同一个线程中创建了多个引擎实例，这些实例必须分别调用 destroyEngine 销毁。
• 通常不建议在移动端设备上创建多于 2 个引擎实例。

destroyEngine

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

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

传入参数

注意

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

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：失败。未创建 RTC engine。

注意

• 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后进房的用户会将先进房的用户踢出房间，并且先进房的用户会收到 onError 回调通知，错误类型详见 ErrorCode 中的 kErrorCodeDuplicateLogin。
• 本地用户调用此方法加入房间成功后，会收到 onRoomStateChanged 回调通知。
• 本地用户调用 setUserVisibility 将自身设为可见后加入房间，远端用户会收到 onUserJoined 回调通知。
• 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本地会收到 onRoomStateChanged；如果加入房间的用户可见，远端用户会收到 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 内置视频采集模块，进行采集。
调用该方法后，本地用户会收到 onVideoDeviceStateChanged 的回调。
本地用户在非隐身状态下调用该方法后，房间中的其他用户会收到 onUserStartVideoCapture 的回调。

注意

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

stopVideoCapture

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

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

注意

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

startAudioCapture

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

开启内部音频采集。默认为关闭状态。
内部采集是指：使用 RTC SDK 内置的视频采集机制进行视频采集。 调用该方法开启后，本地用户会收到 onAudioDeviceStateChanged 的回调。
非隐身用户进房后调用该方法，房间中的其他用户会收到 onUserStartAudioCapture 的回调。

注意

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

stopAudioCapture

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

立即关闭内部音频采集。默认为关闭状态。
内部采集是指：使用 RTC SDK 内置的视频采集机制进行视频采集。 调用该方法，本地用户会收到 onAudioDeviceStateChanged 的回调。
非隐身用户进房后调用该方法，房间中的其他用户会收到 onUserStopAudioCapture 的回调。

注意

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

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 为空

注意

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

updateLocalVideoCanvas

public abstract int com.ss.bytertc.engine.RTCEngine.updateLocalVideoCanvas(
    StreamIndex streamIndex,
    int renderMode,
    int background_color)

修改本地视频渲染模式和背景色。

传入参数

返回值

• 0: 成功
• -1: 失败。VideoCanvas 为空

注意 你可以在本地视频渲染过程中，调用此接口。调用结果会实时生效。

setLocalVideoSink

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

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

传入参数

注意

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

updateRemoteStreamVideoCanvas

public abstract void com.ss.bytertc.engine.RTCEngine.updateRemoteStreamVideoCanvas(
    String roomId,
    String userId,
    StreamIndex streamIndex,
    int renderMode,
    int background_color)

修改远端视频渲染模式和背景色。

传入参数

注意 你可以在远端视频渲染过程中，调用此接口。调用结果会实时生效。

setRemoteVideoCanvas

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

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

传入参数

返回值

• 0：成功
• < 0：失败

注意

• 绑定远端用户的视频流，不应早于收到此用户加入房间的通知 onUserJoined
• 本地用户离开房间时，会解除调用此 API 建立的绑定关系；远端用户离开房间则不会影响。

setLocalVideoMirrorType

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

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

传入参数

注意

• 切换视频源不影响镜像设置。
• 屏幕视频流始终不受镜像设置影响。
• 该接口调用前，各视频源的初始状态如下：

setVideoRotationMode

public abstract int com.ss.bytertc.engine.RTCEngine.setVideoRotationMode(
    VideoRotationMode rotationMode)

设置采集视频的旋转模式。默认以 App 方向为旋转参考系。
接收端渲染视频时，将按照和发送端相同的方式进行旋转。

传入参数

返回值

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

注意

• 旋转仅对内部视频采集生效，不适用于外部视频源和屏幕源。
• 调用该接口时已开启视频采集，将立即生效；调用该接口时未开启视频采集，则将在采集开启后生效。
• 更多信息请参考视频采集方向。

switchCamera

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

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

传入参数

返回值

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

注意

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

setAudioRoute

public abstract int com.ss.bytertc.engine.RTCEngine.setAudioRoute(
    AudioRoute audioRoute)

设置当前音频播放路由。默认使用 setDefaultAudioRoute 中设置的音频路由。
音频播放路由发生变化时，会收到 onAudioRouteChanged 回调。

传入参数

返回值

• 0: 方法调用成功
• < 0: 方法调用失败。失败原因参看 MediaDeviceWarning 回调。指定为 kAudioRouteUnknown 时将会失败。

注意

• 连接有线或者蓝牙音频播放设备后，音频路由将自动切换至此设备。
• 移除后，音频设备会自动切换回原设备。
• 不同音频场景中，音频路由和发布订阅状态到音量类型的映射关系详见 AudioScenarioType 。

setDefaultAudioRoute

public abstract int com.ss.bytertc.engine.RTCEngine.setDefaultAudioRoute(
    AudioRoute route)

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

传入参数

返回值 方法调用结果

• 0: 方法调用成功。立即生效。当所有音频外设移除后，音频路由将被切换到默认设备。
• < 0: 方法调用失败。指定除扬声器和听筒以外的设备将会失败。

注意

• 进房前后都可以调用。
• 更多注意事项参见音频路由。

getAudioRoute

public abstract AudioRoute com.ss.bytertc.engine.RTCEngine.getAudioRoute()

获取当前使用的音频播放路由。

返回值 详见 AudioRoute

注意 要设置音频路由，详见 setAudioRoute。

enableExternalSoundCard

public abstract void com.ss.bytertc.engine.RTCEngine.enableExternalSoundCard(
    boolean enable)

启用匹配外置声卡的音频处理模式

传入参数

注意

• 当采用外接声卡进行音频采集时，建议开启此模式，以获得更好的音质。
• 开启此模式时，仅支持耳机播放。如果需要使用扬声器或者外置音箱播放，关闭此模式。

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 过期前 30 秒，会收到 onTokenWillExpire 回调，此时需要重新获取 Token，并调用此方法更新 Token，否则用户将因为 Token 过期被移出房间。
调用 joinRoom 方法加入房间或断网重连进入房间时，如果 Token 过期或无效，将导致加入房间失败，并会收到 onRoomStateChanged 回调通知，回调错误码为 ErrorCode 中的 ERROR_CODE_INVALID_TOKEN。此时需要重新获取 Token，并调用此方法更新 Token。 更新 Token 后，SDK 会自动加入房间。

传入参数

返回值 方法调用结果。

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

注意 当 Token 过期时，用户将被移出房间并将收到 onError 回调， ERROR_CODE_EXPIRED_TOKEN，此时需要重新获取 Token，并调用 joinRoom 重新加入房间。

setUserVisibility

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

设置用户可见性。默认可见。

传入参数

返回值

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

注意

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

publishStream

public abstract int com.ss.bytertc.engine.RTCEngine.publishStream(
    MediaStreamType type)

在当前所在房间内发布本地通过摄像头/麦克风采集的媒体流

传入参数

返回值 方法调用结果：

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

注意

• 调用 setUserVisibility 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布摄像头音视频流。
• 如果你需要发布屏幕共享流，调用 publishScreen。
• 如果你需要向多个房间发布流，调用 startForwardStreamToRooms。
• 调用此方法后，房间中的所有远端用户会收到 onUserPublishStream 回调通知，其中成功收到了音频流的远端用户会收到 onFirstRemoteAudioFrame 回调，订阅了视频流的远端用户会收到 onFirstRemoteVideoFrameDecoded 回调。
• 调用 unpublishStream 取消发布。

unpublishStream

public abstract int com.ss.bytertc.engine.RTCEngine.unpublishStream(
    MediaStreamType type)

停止将本地摄像头/麦克风采集的媒体流发布到当前所在房间中

传入参数

返回值

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

注意

• 调用 publishStream 手动发布摄像头音视频流后，你需调用此接口停止发布。
• 调用此方法停止发布音视频流后，房间中的其他用户将会收到 onUserUnPublishStream 回调通知。

setCaptureVolume

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

调节音频采集音量

传入参数

注意 在开启音频采集前后，你都可以使用此接口设定采集音量。

setPlaybackVolume

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

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

传入参数

setLocalVoicePitch

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

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

传入参数

enableVocalInstrumentBalance

public abstract void com.ss.bytertc.engine.RTCEngine.enableVocalInstrumentBalance(
    boolean enable)

开启/关闭音量均衡功能。
开启音量均衡功能后，人声的响度会调整为 -16lufs。如果已调用 setAudioMixingLoudness 传入了混音音乐的原始响度，此音乐播放时，响度会调整为 -20lufs。

传入参数

注意 该接口须在调用 startAudioMixing 开始播放音频文件之前调用。

enablePlaybackDucking

public abstract void com.ss.bytertc.engine.RTCEngine.enablePlaybackDucking(
    boolean enable)

打开/关闭音量闪避功能，适用于“一起看”等场景。
开启该功能后，当检测到远端人声时，本地的媒体播放音量会自动减弱，从而保证远端人声的清晰可辨；当远端人声消失时，本地媒体音量会恢复到闪避前的音量水平。

传入参数

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,
    MessageConfig config)

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

传入参数

返回值

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

注意

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

sendUserBinaryMessage

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

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

传入参数

返回值

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

注意

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

login

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

必须先登录，才能发送房间外点对点消息和向应用服务器发送消息
在调用本接口登录后，如果想要登出，需要调用 logout。

传入参数

返回值

• 0：成功
• -1：失败。无效参数
• -2：无效调用。用户已经登录。成功登录后再次调用本接口将收到此返回值
• -3：失败。Engine 为空。调用 createEngine 创建引擎实例后再调用本接口。

注意 本地用户调用此方法登录成功后，会收到 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,
    MessageConfig config)

给房间外指定的用户发送文本消息（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,
    MessageConfig config)

给房间外指定的用户发送二进制消息（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 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 回调通知探测停止。

enableAudioFrameCallback

public abstract void com.ss.bytertc.engine.RTCEngine.enableAudioFrameCallback(
    AudioFrameCallbackMethod method,
    AudioFormat format)

开启音频回调

传入参数

注意 开启音频回调并调用 registerAudioFrameObserver 后，IAudioFrameObserver 会收到对应的音频回调。两者调用顺序没有限制且相互独立。

disableAudioFrameCallback

public abstract void com.ss.bytertc.engine.RTCEngine.disableAudioFrameCallback(
    AudioFrameCallbackMethod method)

关闭音频回调

传入参数

注意 该方法需要在调用 enableAudioFrameCallback 之后调用。

registerAudioFrameObserver

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

注册音频数据回调观察者。

传入参数

返回值

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

注意 注册音频数据回调观察者并调用 enableAudioFrameCallback 后，IAudioFrameObserver 会收到对应的音频回调。

registerAudioProcessor

public abstract int com.ss.bytertc.engine.RTCEngine.registerAudioProcessor(
    IAudioFrameProcessor processor)

注册自定义音频处理器。
注册完成后，你可以调用 enableAudioProcessor，对本地采集或接收到的远端音频进行处理。

传入参数

注意 重复调用此接口时，仅最后一次调用生效。

enableAudioProcessor

public abstract void com.ss.bytertc.engine.RTCEngine.enableAudioProcessor(
    AudioProcessorMethod method,
    AudioFormat format)

获取本地采集的音频帧或接收到的远端音频帧，进行自定义处理。

传入参数

注意

• 在调用此接口前，你需要调用 registerAudioProcessor 注册自定义音频处理器。
• 要关闭音频自定义处理，调用 disableAudioProcessor。

disableAudioProcessor

public abstract void com.ss.bytertc.engine.RTCEngine.disableAudioProcessor(
    AudioProcessorMethod method)

关闭自定义音频处理。

传入参数

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)

废弃
使用 pushExternalVideoFrame(VideoFrame frame) 代替

推送外部视频帧。

传入参数

返回值

• true: 成功
• false: 失败

注意

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

startLiveTranscoding

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

新增转推直播任务，并设置合流的视频视图布局和音频属性。
同一个任务中转推多路直播流时，SDK 会先将多路流合成一路流，然后再进行转推。

传入参数

注意

• 调用该方法后，关于启动结果和推流过程中的错误，会收到 onStreamMixingEvent 回调。
• 调用 stopLiveTranscoding 停止转推直播。

stopLiveTranscoding

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

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

传入参数

updateLiveTranscoding

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

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

传入参数

setVideoCaptureConfig

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

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

传入参数

返回值

• 0: 成功
• < 0: 失败

注意

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

enableSimulcastMode

public abstract int com.ss.bytertc.engine.RTCEngine.enableSimulcastMode(
    boolean enabled)

该方法设置视频流发布端是否开启发布多路编码参数不同的视频流的模式。

传入参数

返回值 方法调用结果：

• 0: 成功
• <0: 失败

注意

• 开启推送多路流前请联系技术支持人员通过配置下发开启该功能。
• 你应在进房前或进房后但未发布流时，调用此方法。
• 开启推送多路视频流模式后，你可以调用 setVideoEncoderConfig 为多路视频流分别设置编码参数。
• 该功能关闭时，或该功能开启但未设置多路流参数时，默认只发一路视频流，该流的编码参数为：分辨率 640px × 360px，帧率 15fps。

setRemoteVideoConfig

public abstract int com.ss.bytertc.engine.RTCEngine.setRemoteVideoConfig(
    String userId,
    RemoteVideoConfig videoConfig)

设置期望订阅的远端视频流的参数。

传入参数

注意

• 该方法仅在发布端调用 enableSimulcastMode 开启了发送多路视频流的情况下生效，此时订阅端将收到来自发布端与期望设置的参数最相近的一路流；否则订阅端只会收到一路参数为分辨率 640px × 360px、帧率 15fps 的视频流。
• 若发布端开启了推送多路流功能，但订阅端不对流参数进行设置，则默认接受发送端设置的分辨率最大的一路视频流。
• 该方法需在进房后调用，若想进房前设置，你需调用 joinRoom，并对 roomConfig 中的 remoteVideoConfig 进行设置。
• 该方法在订阅前后都可调用，订阅后的设置会在重新订阅该流时生效。
• SDK 会根据发布端和所有订阅端的设置灵活调整视频流的参数，具体调整策略详见推送多路流文档。

setVideoEncoderConfig

public abstract int com.ss.bytertc.engine.RTCEngine.setVideoEncoderConfig(
    VideoEncoderConfig max_solution)

视频发布端设置期望发布的最大分辨率视频流参数，包括分辨率、帧率、码率、缩放模式、网络不佳时的回退策略等。
该接口支持设置一路视频流参数，设置多路参数请使用重载 API：setVideoEncoderConfig

传入参数

返回值 方法调用结果：

• 0：成功
• !0：失败

注意

• 若调用该方法设置了期望发布的最大分辨率的流参数之前，已调用 enableSimulcastMode 开启发布多路视频流的模式，SDK 会根据订阅端的设置自动调整发布的流数以及各路流的参数，其中最大分辨率为设置的分辨率，流数最多 4 条，具体参看推送多路流文档；否则仅发布该条最大分辨率的视频流。
• 调用该方法设置多路视频流参数前，SDK 默认仅发布一条分辨率为 640px × 360px，帧率为 15fps 的视频流。
• 该方法适用于摄像头采集的视频流，设置屏幕共享视频流参数参看 setScreenVideoEncoderConfig。

setVideoEncoderConfig

public abstract int com.ss.bytertc.engine.RTCEngine.setVideoEncoderConfig(
    VideoEncoderConfig[] channel_solutions)

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

传入参数

返回值 方法调用结果：

• 0：成功
• !0：失败

注意

• 该方法是否生效取决于是否同时调用了 enableSimulcastMode 开启发布多路参数不同的视频流模式。若未开启推送多路流模式，但调用本方法设置了多个分辨率，SDK 默认发布分辨率最大的一条流，多个分辨率的设置会在开启推送多路流模式之后生效。
• 调用该方法设置多路视频流参数前，SDK 默认仅发布一条分辨率为 640px × 360px，帧率为 15fps 的视频流。
• 调用该方法设置分辨率不同的多条流后，SDK 会根据订阅端设置的期望订阅参数自动匹配发送的流，具体规则参看推送多路流文档。
• 该方法适用于摄像头采集的视频流，设置屏幕共享视频流参数参看 setScreenVideoEncoderConfig。

setScreenVideoEncoderConfig

public abstract int com.ss.bytertc.engine.RTCEngine.setScreenVideoEncoderConfig(
    VideoEncoderConfig screen_solution)

为发布的屏幕共享视频流设置期望的编码参数，包括分辨率、帧率、码率、缩放模式、网络不佳时的回退策略等。

传入参数

返回值 方法调用结果： 0：成功
!0：失败

注意 调用该方法之前，屏幕共享视频流默认的编码参数为：分辨率 1920px × 1080px，帧率 15fps。

subscribeStream

public abstract void com.ss.bytertc.engine.RTCEngine.subscribeStream(
    String uid,
    MediaStreamType type)

订阅房间内指定的通过摄像头/麦克风采集的媒体流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 你必须先通过 onUserPublishStream 回调获取当前房间里的远端摄像头音视频流信息，然后调用本方法按需订阅。
• 调用该方法后，你会收到 onStreamSubscribed 通知方法调用结果。
• 关于其他调用异常，你会收到 onStreamStateChanged 回调通知，具体异常原因参看 ErrorCode。

unsubscribeStream

public abstract void com.ss.bytertc.engine.RTCEngine.unsubscribeStream(
    String uid,
    MediaStreamType type)

取消订阅房间内指定的通过摄像头/麦克风采集的媒体流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 调用该方法后，你会收到 onStreamSubscribed 通知流的退订结果。
• 关于其他调用异常，你会收到 onStreamStateChanged 回调通知，具体失败原因参看 ErrorCode。

subscribeScreen

public abstract void com.ss.bytertc.engine.RTCEngine.subscribeScreen(
    String uid,
    MediaStreamType type)

订阅房间内指定的远端屏幕共享音视频流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 你必须先通过 onUserPublishScreen 回调获取当前房间里的远端屏幕流信息，然后调用本方法按需订阅。
• 调用该方法后，你会收到 onStreamSubscribed 通知流的订阅结果。
• 关于其他调用异常，你会收到 onStreamStateChanged 回调通知，具体异常原因参看 ErrorCode。

unsubscribeScreen

public abstract void com.ss.bytertc.engine.RTCEngine.unsubscribeScreen(
    String uid,
    MediaStreamType type)

取消订阅房间内指定的远端屏幕共享音视频流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 调用该方法后，你会收到 onStreamSubscribed 通知流的退订结果。
• 关于其他调用异常，你会收到 onStreamStateChanged 回调通知，具体失败原因参看 ErrorCode。

pushExternalAudioFrame

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

推送自定义采集的音频数据到 RTC SDK。

传入参数

返回值 方法调用结果

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

注意

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

setAudioSourceType

public abstract int com.ss.bytertc.engine.RTCEngine.setAudioSourceType (
    AudioSourceType type)

切换音频采集方式

传入参数

返回值 方法调用结果：

• >0: 切换成功。
• -1：切换失败。

注意

• 进房前后调用此方法均有效。
• 如果你调用此方法由内部采集切换至自定义采集，SDK 会自动关闭内部采集。然后，调用 pushExternalAudioFrame 推送自定义采集的音频数据到 RTC SDK 用于传输。
• 如果你调用此方法由自定义采集切换至内部采集，你必须再调用 startAudioCapture 手动开启内部采集。

setAudioRenderType

public abstract int com.ss.bytertc.engine.RTCEngine.setAudioRenderType (
    AudioRenderType type)

切换音频渲染方式

传入参数

返回值 方法调用结果：

• >0: 切换成功。
• -1：切换失败。

注意

• 进房前后调用此方法均有效。
• 如果你调用此方法切换至自定义渲染，调用 pullExternalAudioFrame 获取音频数据。

pullExternalAudioFrame

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

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

传入参数

返回值 方法调用结果

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

注意

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

publishScreen

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

在当前所在房间内发布本地屏幕共享音视频流

传入参数

返回值

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

注意

• 调用 setUserVisibility 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布屏幕流。
• 调用该方法后，房间中的所有远端用户会收到 onUserPublishScreen 回调，其中成功收到音频流的远端用户会收到 onFirstRemoteAudioFrame 回调，订阅了视频流的远端用户会收到 onFirstRemoteVideoFrameDecoded 回调。
• 如果你需要向多个房间发布流，调用 startForwardStreamToRooms。
• 调用 unpublishScreen 取消发布。

unpublishScreen

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

停止将本地屏幕共享音视频流发布到当前所在房间中

传入参数

返回值

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

注意

• 调用 publishScreen 发布屏幕流后，你需调用此接口停止发布。
• 调用此方法停止发布屏幕音视频流后，房间中的其他用户将会收到 onUserUnPublishScreen 回调。

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。

传入参数

setMultiDeviceAVSync

public abstract int com.ss.bytertc.engine.RTCEngine.setMultiDeviceAVSync(
    String audioUserId)

设置发流端音画同步。
当同一用户同时使用两个通话设备分别采集发送音频和视频时，有可能会因两个设备所处的网络环境不一致而导致发布的流不同步，此时你可以在视频发送端调用该接口，SDK 会根据音频流的时间戳自动校准视频流，以保证接收端听到音频和看到视频在时间上的同步性。

传入参数

返回值 方法调用结果：

• 0：成功
• !0：失败

注意

• 该方法在进房前后均可调用。
• 进行音画同步的音频发布用户 ID 和视频发布用户 ID 须在同一个 RTC 房间内。
• 调用该接口后音画同步状态发生改变时，你会收到 onAVSyncStateChange 回调。
• 同一 RTC 房间内允许存在多个音视频同步关系，但需注意单个音频源不支持与多个视频源同时同步。
• 如需更换同步音频源，再次调用该接口传入新的 audioUserId 即可；如需更换同步视频源，需先解除当前的同步关系，后在新视频源端开启同步。

setPublishFallbackOption

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

设置发布的音视频流的回退选项。
你可以调用该接口设置网络不佳或设备性能不足时从大流起进行降级处理，以保证通话质量。

传入参数

返回值 方法调用结果：

• 0：成功
• < 0：失败

注意

• 该方法仅在调用 enableSimulcastMode 开启了发送多路视频流的情况下生效。
• 该方法必须在进房前设置，进房后设置或更改设置无效。
• 设置回退后，本地发布的音视频流发生回退或从回退中恢复时，远端会收到 onSimulcastSubscribeFallback 回调通知。
• 你可以调用客户端 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。

setSubscribeFallbackOption

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

设置订阅的音视频流的回退选项。
你可调用该接口设置网络不佳或设备性能不足时允许订阅流进行降级或只订阅音频流，以保证通话流畅。

传入参数

返回值 方法调用结果：

• 0：成功
• < 0：失败

注意

• 你必须在进房前设置，进房后设置或更改设置无效。
• 设置回退选项后，订阅的音视频流发生回退或从回退中恢复时，会收到 onSimulcastSubscribeFallback 和 onRemoteVideoSizeChanged 回调通知。
• 你可以调用 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。

setRemoteUserPriority

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

设置用户优先级。

传入参数

返回值

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

注意

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

sendSEIMessage

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

在视频通信时，通过视频帧发送 SEI 数据。StreamMain 流当是内部源且摄像头处于关闭状态时调用本函数，SDK engine 会构造一个视频黑帧发送 SEI 信息

传入参数

返回值

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

注意

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

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: 许可证验证成功
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• <0: 其他错误，具体参看错误码表

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

initVirtualBackground

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

虚拟背景功能初始化。

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• > 40000: 调用失败，特效 SDK 授权错误，具体错误码请参考 错误码表。
• < 0: 调用失败，特效 SDK 内部错误，具体错误码请参考 错误码表。

enableVirtualBackground

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

开启虚拟背景。

传入参数

返回值

• 0: 调用成功。
• < 0: 调用失败，特效 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: 调用失败，具体错误码请参考 错误码表。

注意 调用 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: 成功
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• <0: 其他错误，具体参看错误码表

注意

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

setVideoEffectNodes

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

设置视频特效素材包

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• < 0: 调用失败。具体错误码，参看 错误码表。

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

updateVideoEffectNode

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

设置特效强度

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• < 0: 调用失败。具体错误码，参看 错误码表。

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

setVideoEffectColorFilter

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

设置颜色滤镜

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• < 0: 调用失败。具体错误码，参看 错误码表。

setVideoEffectColorFilterIntensity

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

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

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• < 0: 调用失败。具体错误码，参看 错误码表。

registerFaceDetectionObserver

public abstract int com.ss.bytertc.engine.RTCEngine.registerFaceDetectionObserver(
    IFaceDetectionObserver observer,
    int interval)

注册人脸检测结果回调观察者
注册此观察者后，你会周期性收到 onFaceDetectResult 回调。

传入参数

返回值

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

enableEffectBeauty

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

开启/关闭基础美颜

传入参数

返回值

• 0: 开启/关闭成功。
• 1000: 未集成特效 SDK。
• 1001: RTC SDK 版本不支持此功能。
• 1002: 特效 SDK 当前版本不支持此功能，建议使用特效 SDK V4.3.1 版本。
• 1003: 联系技术支持人员。
• 1004: 正在下载相关资源，下载完成后生效。
• <0: 调用失败，特效 SDK 内部错误，具体错误码请参考错误码表。

注意

• 本方法不能与高级视频特效接口共用。如已购买高级视频特效，建议调用 enableVideoEffect 使用高级特效、贴纸功能等。
• 使用此功能需要集成特效 SDK，建议使用特效 SDK V4.3.1+ 版本。
• 调用 setBeautyIntensity 设置基础美颜强度。若在调用本方法前没有设置美颜强度，则初始美白、磨皮、锐化强度均为 0.5。
• 本方法仅适用于视频源，不适用于屏幕源。

setBeautyIntensity

public abstract int com.ss.bytertc.engine.RTCEngine.setBeautyIntensity(
    EffectBeautyMode beautyMode,
    float intensity)

调整基础美颜强度

传入参数

返回值

• 0: 开启成功。
• 1000: 未集成特效 SDK。
• 1001: RTC SDK 版本不支持此功能。
• <0: 调用失败，特效 SDK 内部错误，具体错误码请参考错误码表。

注意

• 若在调用 enableEffectBeauty 前设置美颜强度，则对应美颜功能的强度初始值会根据设置更新。
• 销毁引擎后，美颜功能强度恢复默认值。

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,
    RecordingType recordingType)

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

传入参数

返回值 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

setScreenAudioSourceType

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

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

传入参数

注意

• 默认采集方式是 RTC SDK 内部采集。
• 你应该在 publishScreen 前，调用此方法。否则，你将收到 onWarning 的报错：WARNING_CODE_SET_SCREEN_AUDIO_SOURCE_TYPE_FAILED。
• 如果设定为内部采集，你必须再调用 startScreenCapture 开始采集。
• 如果设定为自定义采集，你必须再调用 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 × frame.channel × 2。
• 此函数运行在用户级线程内。若同时运行其他进程，将导致本进程中断。
• 调用此接口将自定义采集的音频帧推送到 RTC SDK 后，你必须调用 publishScreen 将采集到的屏幕音频推送到远端。在调用 publishScreen 前，推送到 RTC SDK 的音频帧信息会丢失。

startScreenCapture

public abstract void com.ss.bytertc.engine.RTCEngine.startScreenCapture(
    ScreenMediaType type,
    Intent mediaProjectionResultData)

使用 RTC SDK 内部采集模块开始采集屏幕音频流和（或）视频流。

传入参数

注意

• 采集后，你还需要调用 publishScreen 发布采集到的屏幕音视频。
• 开启屏幕音频/视频采集成功后，本地用户会收到 onVideoDeviceStateChanged 和 onAudioDeviceStateChanged 的回调。
• 要关闭屏幕音视频内部采集，调用 stopScreenCapture。

updateScreenCapture

public abstract void com.ss.bytertc.engine.RTCEngine.updateScreenCapture(
    ScreenMediaType type)

使用 RTC SDK 内部屏幕采集后，更新采集的媒体类型。

传入参数

返回值

• 0: 成功
• -1: 失败

注意 在 startScreenCapture 后调用该方法。

stopScreenCapture

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

在屏幕共享时，停止使用 RTC SDK 内部采集方式采集屏幕音视频。

注意

• 要开始屏幕音视频内部采集，调用 startScreenCapture。

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 格式的视频帧，且视频流协议格式须为 Annex B 格式。
• 该函数运行在用户调用线程内
• 推送自定义编码视频帧前，必须调用 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。

注意 在采用 CHANNEL_PROFILE_LIVE_BROADCASTING 作为房间模式时，此消息一定会送达。在其他房间模式下，如果本地用户未说话，此消息不一定会送达。

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 关闭内部采集后失效。

isCameraFocusPositionSupported

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

检查当前使用的摄像头是否支持手动对焦。

返回值

• true: 支持。
• false: 不支持。

注意 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集，才能检查摄像头是否支持手动对焦。

setCameraFocusPosition

public abstract int com.ss.bytertc.engine.RTCEngine.setCameraFocusPosition(
    float x,
    float y)

设置当前使用的摄像头的对焦点。

传入参数

返回值

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

注意

• 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集，并且使用 SDK 内部渲染时，才能设置对焦点。
• 移动设备时，自动取消对焦点设置。
• 调用 stopVideoCapture 关闭内部采集后，设置的对焦点失效。

isCameraExposurePositionSupported

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

检查当前使用的摄像头是否支持手动设置曝光点。

返回值

• true: 支持。
• false: 不支持。

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

setCameraExposurePosition

public abstract int com.ss.bytertc.engine.RTCEngine.setCameraExposurePosition(
    float x,
    float y)

设置当前使用的摄像头的曝光点

传入参数

返回值

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

注意

• 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集，并且使用SDK内部渲染时，才能设置曝光点。
• 移动设备时，自动取消曝光点设置。
• 调用 stopVideoCapture 关闭内部采集后，设置的曝光点失效。

setCameraExposureCompensation

public abstract int com.ss.bytertc.engine.RTCEngine.setCameraExposureCompensation(
    float val)

设置当前使用的摄像头的曝光补偿。

传入参数

返回值

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

注意

• 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能设置曝光补偿。
• 调用 stopVideoCapture 关闭内部采集后，设置的曝光补偿失效。

startForwardStreamToRooms

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

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

传入参数

返回值

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

注意

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

updateForwardStreamToRooms

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

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

传入参数

返回值

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

注意

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

stopForwardStreamToRooms

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

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

注意

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

pauseForwardStreamToAllRooms

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

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

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

resumeForwardStreamToAllRooms

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

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

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

muteAudioPlayback

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

控制本地音频流播放状态：播放/不播放

传入参数

注意 本方法仅控制本地收到音频流的播放状态，并不影响本地音频播放设备。

startPushPublicStream

public abstract int com.ss.bytertc.engine.RTCEngine.startPushPublicStream(
    String publicStreamId,
    PublicStreaming publicStreamParam)

发布一路公共流
公共流是指不属于任何房间，也不属于任何用户的媒体流。使用同一 appID 的用户，可以调用 startPlayPublicStream 获取和播放指定的公共流。

传入参数

返回值 0: 成功。同时将收到 onPushPublicStreamResult 回调。

• !0: 失败。当参数不合法或参数为空，调用失败。

注意

• 同一用户使用同一公共流 ID 多次调用本接口无效。如果你希望更新公共流参数，调用 updatePublicStreamParam 接口。
• 不同用户使用同一公共流 ID 多次调用本接口时，RTC 将使用最后一次调用时传入的参数更新公共流。
• 使用不同的 ID 多次调用本接口可以发布多路公共流。
• 调用 stopPushPublicStream 停止推公共流。

stopPushPublicStream

public abstract int com.ss.bytertc.engine.RTCEngine.stopPushPublicStream(
    String publicStreamId)

停止发布当前用户发布的公共流
关于发布公共流，查看 startPushPublicStream

传入参数

返回值

• 0: 成功
• !0: 失败

updatePublicStreamParam

public abstract int com.ss.bytertc.engine.RTCEngine.updatePublicStreamParam(
    String publicStreamId,
    PublicStreaming publicStreamParam)

更新公共流参数
关于发布公共流，查看 startPushPublicStream。

传入参数

返回值

• 0: 成功
• !0: 失败

startPlayPublicStream

public abstract int com.ss.bytertc.engine.RTCEngine.startPlayPublicStream(
    String publicStreamId)

订阅指定公共流
无论用户是否在房间内，都可以调用本接口获取和播放指定的公共流。

传入参数

返回值

• 0: 成功。同时将收到 onPlayPublicStreamResult 回调。
• !0: 失败。当参数不合法或参数为空，调用失败。

注意

• 在调用本接口之前，建议先绑定渲染视图。
• 调用 setPublicStreamVideoCanvas 绑定内部渲染视图：
• 调用 setPublicStreamVideoSink 绑定自定义渲染视图：
• 调用本接口后，可以通过 onFirstPublicStreamVideoFrameDecoded 和 onFirstPublicStreamAudioFrameDecodedonFirstPublicStreamAduioFrameDecoded 回调公共流的视频和音频首帧解码情况。
• 调用本接口后，可以通过 onPublicStreamSEIMessageReceived 回调公共流中包含的 SEI 信息。
• 调用 stopPlayPublicStream 取消订阅公共流。

stopPlayPublicStream

public abstract int com.ss.bytertc.engine.RTCEngine.stopPlayPublicStream(
    String publicStreamId)

取消订阅指定公共流
关于订阅公共流，查看 startPlayPublicStream。

传入参数

返回值

• 0：成功
• !0：失败

setPublicStreamVideoCanvas

public abstract int com.ss.bytertc.engine.RTCEngine.setPublicStreamVideoCanvas(
    String publicStreamId,
    VideoCanvas videoCanvas)

为指定公共流绑定内部渲染视图。

传入参数

返回值

• 0：成功
• <0：失败

setPublicStreamVideoSink

public abstract void com.ss.bytertc.engine.RTCEngine.setPublicStreamVideoSink(
    String publicStreamId,
    IVideoSink videoSink,
    @IVideoSink.PixelFormat int requiredFormat)

为指定公共流绑定自定义渲染器。详见自定义视频渲染。

传入参数

返回值

• 0: 成功
• <0: 失败

setVideoWatermark

public abstract void com.ss.bytertc.engine.RTCEngine.setVideoWatermark(
    StreamIndex streamIndex,
    String imagePath,
    RTCWatermarkConfig watermarkConfig)

在指定视频流上添加水印。

传入参数

注意

• 调用 clearVideoWatermark 移除指定视频流的水印。
• 同一路流只能设置一个水印，新设置的水印会代替上一次的设置。你可以多次调用本方法来设置不同流的水印。
• 进入房间前后均可调用此方法。
• 若开启本地预览镜像，或开启本地预览和编码传输镜像，则远端水印均不镜像；在开启本地预览水印时，本端水印会镜像。
• 开启大小流后，水印对大小流均生效，且针对小流进行等比例缩小。

clearVideoWatermark

public abstract void com.ss.bytertc.engine.RTCEngine.clearVideoWatermark(
    StreamIndex streamIndex)

移除指定视频流的水印。

传入参数

startCloudProxy

public abstract void com.ss.bytertc.engine.RTCEngine.startCloudProxy(
    List<CloudProxyInfo> cloudProxiesInfo)

开启云代理

传入参数

注意

• 在加入房间前调用此接口
• 在开启云代理后，进行通话前网络探测
• 开启云代理后，并成功链接云代理服务器后，会收到 onCloudProxyConnected。
• 要关闭云代理，调用 stopCloudProxy。

stopCloudProxy

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

关闭云代理

注意 要开启云代理，调用 startCloudProxy。

startEchoTest

public abstract int com.ss.bytertc.engine.RTCEngine.startEchoTest(
    EchoTestConfig config,
    int delayTime)

开启音视频回路测试。
在进房前，用户可调用该接口对音视频通话全链路进行检测，包括对音视频设备以及用户上下行网络的检测，从而帮助用户判断是否可以正常发布和接收音视频流。
开始检测后，SDK 会录制你声音或视频。如果你在设置的延时范围内收到了回放，则视为音视频回路测试正常。

传入参数

返回值 方法调用结果：

• 0：成功
• -1：失败，当前用户已经在检测中
• -2：失败，用户已进房
• -3：失败，音视频均未采集
• -4：失败，参数异常
• -5：失败，已经存在相同 roomId 的房间

注意

• 调用该方法开始音视频回路检测后，你可以调用 stopEchoTest 立即结束测试，也可等待测试 60s 后自动结束，以更换设备进行下一次测试，或进房。
• 在该方法之前调用的所有跟设备控制、流控制相关的方法均在开始检测时失效，在结束检测后恢复生效。
• 在调用 startEchoTest 和 stopEchoTest 之间调用的所有跟设备采集、流控制、进房相关的方法均不生效，并会收到 onWarning 回调，提示警告码为 WARNING_CODE_IN_ECHO_TEST_MODE。
• 音视频回路检测的结果会通过 onEchoTestResult 回调通知。

stopEchoTest

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

停止音视频回路测试。
调用 startEchoTest 开启音视频回路检测后，你必须调用该方法停止检测。

返回值 方法调用结果：

• 0：成功
• -1：失败，未开启回路检测

注意 音视频回路检测结束后，所有对系统设备及音视频流的控制均会恢复到开始检测前的状态。

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)

预加载指定音频文件到内存中，以避免频繁播放时的重复加载。

传入参数

注意

• 本方法只是预加载指定音频文件，只有调用 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)

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

传入参数

注意 在播放在线文件时，调用此接口可能造成播放延迟的现象。

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 回调报错

setAudioMixingPlaybackSpeed

public abstract int com.ss.bytertc.engine.audio.IAudioMixingManager.setAudioMixingPlaybackSpeed(
    int mixId,
    int speed)

设置混音时音频文件的播放速度

传入参数

注意

• 暂不支持对 PCM 音频数据进行变速调整。
• 你需要在调用 startAudioMixing 开始混音，并且收到onAudioMixingStateChanged 回调提示 AudioMixingState 状态为 AUDIO_MIXING_STATE_PLAYING，AudioMixingError 错误码为 AUDIO_MIXING_ERROR_OK 之后调用该方法。
• 在 stopAudioMixing 停止混音或 unloadAudioMixing 卸载音频文件后调用该 API，会收到状态为 AUDIO_MIXING_STATE_FAILED 错误码为 AUDIO_MIXING_ERROR_ID_NOT_FOUND 的 onAudioMixingStateChanged 回调。

setAudioMixingLoudness

public abstract void com.ss.bytertc.engine.audio.IAudioMixingManager.setAudioMixingLoudness(
    int mixId,
    float loudness)

如果你需要使用 enableVocalInstrumentBalance 对混音使音频文件/PCM 音频数据进行音量调整，你必须通过此接口传入其原始响度。

传入参数

注意 建议在 startAudioMixing 开始播放音频文件之前调用该接口，以免播放过程中的音量突变导致听感体验下降。

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 播放的音乐无效。

IRangeAudio

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

范围语音接口实例

成员函数

函数说明

enableRangeAudio

void com.ss.bytertc.engine.audio.IRangeAudio.enableRangeAudio(
    boolean enable)

开启/关闭范围语音功能。
范围语音是指，在同一 RTC 房间中设定的音频接收距离范围内，本地用户收听到的远端用户音频音量会随着远端用户的靠近/远离而放大/衰减；若远端用户在房间内的位置超出设定范围，则本地用户无法接收其音频。音频接收范围设置参看 updateReceiveRange。

传入参数

注意 该方法进房前后都可调用，为保证进房后范围语音效果的平滑切换，你需在该方法前先调用 updatePosition 设置自身位置坐标，然后开启该方法收听范围语音效果。

updatePosition

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

更新本地用户在房间内空间直角坐标系中的位置坐标。

传入参数

返回值 方法调用结果：

• 0：成功；
• !0：失败。

注意

• 调用该接口更新坐标后，你需调用 enableRangeAudio 开启范围语音功能以收听范围语音效果。
• 若此前你已调用 registerRangeAudioObserver 注册了范围语音衰减系数监测器，房间内有任何用户调用该接口更新自身位置坐标后，你都会收到 OnRangeAudioInfo 回调。

updateReceiveRange

int com.ss.bytertc.engine.audio.IRangeAudio.updateReceiveRange(
    ReceiveRange range)

更新本地用户的音频收听范围。

传入参数

返回值 方法调用结果：

• 0：成功；
• !0: 失败。

注意 若此前你已调用 registerRangeAudioObserver 注册了范围语音衰减系数监测器，房间内有任何用户调用该接口更新音频收听范围后，你都会收到 OnRangeAudioInfo 回调。

registerRangeAudioObserver

void com.ss.bytertc.engine.audio.IRangeAudio.registerRangeAudioObserver(
    IRangeAudioObserver observer)

设置范围语音衰减系数监测器。

传入参数

注意 该方法仅适用于手动订阅模式，自动订阅无需设置。

ISpatialAudio

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

空间音频接口实例

成员函数

函数说明

enableSpatialAudio

void com.ss.bytertc.engine.audio.ISpatialAudio.enableSpatialAudio(
    boolean enable)

开启/关闭空间音频功能。

传入参数

注意 该方法仅开启空间音频功能，你须调用 updatePosition 设置自身位置坐标后方可收听空间音频效果。空间音频相关 API 和调用时序详见空间音频。

updatePosition

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

更新本地用户在房间内空间直角坐标系中的位置坐标。

传入参数

返回值

• 0: 成功；
• !0: 失败。

注意 调用该接口更新坐标前，你需调用 enableSpatialAudio 开启空间音频功能。 空间音频相关 API 和调用时序详见空间音频。

updateSelfOrientation

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

更新本地用户在空间音频坐标系下的朝向。

传入参数

返回值 方法调用结果：

• 0：成功
• !0：失败

注意

• 空间音频相关 API 和调用时序详见空间音频。
• 调用 disableRemoteOrientation 可忽略远端用户朝向。

disableRemoteOrientation

void com.ss.bytertc.engine.audio.ISpatialAudio.disableRemoteOrientation()

参与通话的各端调用本接口后，将忽略远端用户的朝向，认为所有远端用户都面向本地用户。
如果此后调用 updateSelfOrientation 更新本地用户朝向，远端用户无法感知这些变化，但本地用户接收音频时可以感知自身朝向改变带来的音频效果变化。

注意

• 进房前后都可以调用该接口。
• 调用本接口关闭朝向功能后，在当前的空间音频实例的生命周期内无法再次开启。

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 环境即将销毁时，收到此回调。此时，你可以释放纹理等资源。

RTCRoom

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

成员函数

函数说明

destroy

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

退出并销毁调用 createRoom 所创建的房间。

joinRoom

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

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

传入参数

返回值

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

注意

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

setRTCRoomEventHandler

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

通过设置房间事件 handler，监听此对象对应的回调事件。

传入参数

leaveRoom

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

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

注意

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

setUserVisibility

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

设置用户可见性。默认可见。

传入参数

返回值

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

注意

• 在加入房间前后，用户均可调用此方法设置用户可见性。
• 在房间内，调用此方法成功切换用户可见性后，房间内其他用户会收到相应的回调通知：
• 从可见换至不可见时，房间内其他用户会收到 onUserJoined；
• 从不可见切换至可见时，房间内其他用户会收到 onUserLeave 。
• 若调用该方法将可见性设为 false，此时尝试发布流会收到 WARNING_CODE_PUBLISH_STREAM_FORBIDEN 警告。

updateToken

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

更新 Token。
用于加入房间的 Token 有一定的有效期。在 Token 过期前 30 秒，会收到 onTokenWillExpire 回调，此时需要重新获取 Token，并调用此方法更新 Token，否则用户将因为 Token 过期被移出房间。
调用 joinRoom 方法加入房间或断网重连进入房间时，如果 Token 过期或无效，将导致加入房间失败，并会收到 onRoomStateChanged 回调通知，回调错误码为 ErrorCode 中的 ERROR_CODE_INVALID_TOKEN。此时需要重新获取 Token，并调用此方法更新 Token。

传入参数

注意 当 Token 过期时，用户将被移出房间并将收到 onStreamStateChanged 回调，错误码为 ERROR_CODE_EXPIRED_TOKEN，此时需要重新获取 Token，并调用 joinRoom 重新加入房间。

sendUserMessage

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

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

传入参数

注意

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

sendUserBinaryMessage

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

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

传入参数

注意

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

sendRoomMessage

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

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

传入参数

注意

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

sendRoomBinaryMessage

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

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

传入参数

注意

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

setMultiDeviceAVSync

public abstract int com.ss.bytertc.engine.RTCRoom.setMultiDeviceAVSync(
    String audioUserId)

设置发流端音画同步。
当同一用户同时使用两个通话设备分别采集发送音频和视频时，有可能会因两个设备所处的网络环境不一致而导致发布的流不同步，此时你可以在视频发送端调用该接口，SDK 会根据音频流的时间戳自动校准视频流，以保证接收端听到音频和看到视频在时间上的同步性。

传入参数

返回值 方法调用结果：

• 0：成功
• !0：失败

注意

• 该方法在进房前后均可调用。
• 进行音画同步的音频发布用户 ID 和视频发布用户 ID 须在同一个 RTC 房间内。
• 调用该接口后音画同步状态发生改变时，你会收到 onAVSyncStateChange 回调。
• 同一 RTC 房间内允许存在多个音视频同步关系，但需注意单个音频源不支持与多个视频源同时同步。
• 如需更换同步音频源，再次调用该接口传入新的 audioUserId 即可；如需更换同步视频源，需先解除当前的同步关系，后在新视频源端开启同步。

setRemoteVideoConfig

public abstract void com.ss.bytertc.engine.RTCRoom.setRemoteVideoConfig(
    String userId,
    RemoteVideoConfig remoteVideoConfig)

设置期望订阅的远端视频流的参数。

传入参数

注意

• 该方法仅在发布端调用 enableSimulcastMode 开启了发送多路视频流的情况下生效，此时订阅端将收到来自发布端与期望设置的参数最相近的一路流；否则订阅端只会收到一路参数为分辨率 640px × 360px、帧率 15fps 的视频流。
• 若发布端开启了推送多路流功能，但订阅端不对流参数进行设置，则默认接受发送端设置的分辨率最大的一路视频流。
• 该方法需在进房后调用，若想进房前设置，你需调用 joinRoom，并对 roomConfig 中的 remoteVideoConfig 进行设置。
• 该方法在订阅前后都可调用，订阅后的设置会在重新订阅该流时生效。
• SDK 会根据发布端和所有订阅端的设置灵活调整视频流的参数，具体调整策略详见推送多路流文档。

publishStream

public abstract void com.ss.bytertc.engine.RTCRoom.publishStream(
    MediaStreamType type)

在当前所在房间内发布本地通过摄像头/麦克风采集的媒体流

传入参数

注意

• 多房间模式下默认不自动发布流，你需调用该方法手动发布流。
• 调用 setUserVisibility 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布摄像头音视频流。
• 如果你需要发布屏幕共享流，调用 publishScreen。
• 如果你需要向多个房间发布流，调用 startForwardStreamToRooms。
• 调用此方法后，房间中的所有远端用户会收到 onUserPublishStream 回调通知，其中成功收到了音频流的远端用户会收到 onFirstRemoteAudioFrame 回调，订阅了视频流的远端用户会收到 onFirstRemoteVideoFrameDecoded 回调。
• 调用 unpublishStream 取消发布。

unpublishStream

public abstract void com.ss.bytertc.engine.RTCRoom.unpublishStream(
    MediaStreamType type)

停止将本地摄像头/麦克风采集的媒体流发布到当前所在房间中

传入参数

注意

• 调用 publishStream 手动发布摄像头音视频流后，你需调用此接口停止发布。
• 调用此方法停止发布音视频流后，房间中的其他用户将会收到 onUserUnPublishStream 回调通知。

publishScreen

public abstract void com.ss.bytertc.engine.RTCRoom.publishScreen(
    MediaStreamType type)

在当前所在房间内发布本地屏幕共享音视频流

传入参数

注意

• 调用 setUserVisibility 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布屏幕流。
• 调用该方法后，房间中的所有远端用户会收到 onUserPublishScreen 回调，其中成功收到音频流的远端用户会收到 onFirstRemoteAudioFrame 回调，订阅了视频流的远端用户会收到 onFirstRemoteVideoFrameDecoded 回调。
• 如果你需要向多个房间发布流，调用 startForwardStreamToRooms。
• 调用 unpublishScreen 取消发布。

unpublishScreen

public abstract void com.ss.bytertc.engine.RTCRoom.unpublishScreen(
    MediaStreamType type)

停止将本地屏幕共享音视频流发布到当前所在房间中

传入参数

注意

• 调用 publishScreen 发布屏幕流后，你需调用此接口停止发布。
• 调用此方法停止发布屏幕音视频流后，房间中的其他用户将会收到 onUserUnPublishScreen 回调。

subscribeStream

public abstract void com.ss.bytertc.engine.RTCRoom.subscribeStream(
    String uid,
    MediaStreamType type)

订阅房间内指定的通过摄像头/麦克风采集的媒体流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 你必须先通过 onUserPublishStream 回调获取当前房间里的远端摄像头音视频流信息，然后调用本方法按需订阅。
• 调用该方法后，你会收到 onStreamSubscribed 通知方法调用结果。
• 关于其他调用异常，你会收到 onStreamStateChanged 回调通知，具体异常原因参看 ErrorCode。

unsubscribeStream

public abstract void com.ss.bytertc.engine.RTCRoom.unsubscribeStream(
    String uid,
    MediaStreamType type)

取消订阅房间内指定的通过摄像头/麦克风采集的媒体流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 调用该方法后，你会收到 onStreamSubscribed 通知流的退订结果。
• 关于其他调用异常，你会收到 onStreamStateChanged 回调通知，具体失败原因参看 ErrorCode。

subscribeScreen

public abstract void com.ss.bytertc.engine.RTCRoom.subscribeScreen(
    String uid,
    MediaStreamType type)

订阅房间内指定的远端屏幕共享音视频流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 你必须先通过 onUserPublishScreen 回调获取当前房间里的远端屏幕流信息，然后调用本方法按需订阅。
• 调用该方法后，你会收到 onStreamSubscribed 通知流的订阅结果。
• 关于其他调用异常，你会收到 onStreamStateChanged 回调通知，具体异常原因参看 ErrorCode。

unsubscribeScreen

public abstract void com.ss.bytertc.engine.RTCRoom.unsubscribeScreen(
    String uid,
    MediaStreamType type)

取消订阅房间内指定的远端屏幕共享音视频流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 调用该方法后，你会收到 onStreamSubscribed 通知流的退订结果。
• 关于其他调用异常，你会收到 onStreamStateChanged 回调通知，具体失败原因参看 ErrorCode。

pauseAllSubscribedStream

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

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

传入参数