# ISpatialAudio ```java public interface com.ss.bytertc.engine.audio.ISpatialAudio ``` 空间音频接口实例 ## 成员函数 | 返回 | 名称 | | --- | --- | | void | [enableSpatialAudio](#ISpatialAudio-enablespatialaudio) | | void | [disableRemoteOrientation](#ISpatialAudio-disableremoteorientation) | | int | [updateSelfPosition](#ISpatialAudio-updateselfposition) | | int | [updateRemotePosition](#ISpatialAudio-updateremoteposition) | | int | [removeRemotePosition](#ISpatialAudio-removeremoteposition) | | int | [removeAllRemotePosition](#ISpatialAudio-removeallremoteposition) | ## 函数说明 ### enableSpatialAudio ```java void com.ss.bytertc.engine.audio.ISpatialAudio.enableSpatialAudio(boolean enable) ``` 开启/关闭空间音频功能。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 是否开启空间音频功能：

true：开启
false：关闭（默认）

| **注意** 该方法仅开启空间音频功能，你须调用 [updateSelfPosition](#ISpatialAudio-updateselfposition) 设置自身位置坐标后方可收听空间音频效果。空间音频相关 API 和调用时序详见[空间音频](https://www.volcengine.com/docs/6348/93903)。 ### disableRemoteOrientation ```java void com.ss.bytertc.engine.audio.ISpatialAudio.disableRemoteOrientation() ``` 关闭本地用户朝向对本地用户发声效果的影响。调用此接口后，房间内的其他用户收听本地发声时，声源都在收听者正面。 **注意** - 调用本接口关闭朝向功能后，在当前的空间音频实例的生命周期内无法再次开启。 - 调用此接口不影响本地用户收听朝向的音频效果。要改变本地用户收听朝向，参看 [updateSelfPosition](#ISpatialAudio-updateselfposition) 和 [updateRemotePosition](#ISpatialAudio-updateremoteposition) 。 ### updateSelfPosition ```java int com.ss.bytertc.engine.audio.ISpatialAudio.updateSelfPosition(PositionInfo positionInfo) ``` > Available since 3.52 设置本地用户在自建空间直角坐标系中的收听坐标和收听朝向，以实现本地用户预期的空间音频收听效果。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | positionInfo | PositionInfo | 空间音频位置信息。参看 [PositionInfo](70083#PositionInfo)。 | **返回值** - 0：成功。 - < 0：失败。 - -2：失败，原因是校验本地用户的三维朝向信息时，三个向量没有两两垂直。 **注意** - 该方法需在进房后调用。 - 调用该接口更新坐标前，你需调用 [enableSpatialAudio](#ISpatialAudio-enablespatialaudio) 开启空间音频功能。空间音频相关 API 和调用时序详见[空间音频](https://www.volcengine.com/docs/6348/93903)。 - 调用此接口在本地进行的设定对其他用户的空间音频收听效果不会产生任何影响。 ### updateRemotePosition ```java int com.ss.bytertc.engine.audio.ISpatialAudio.updateRemotePosition( String uid, PositionInfo positionInfo ) ``` > Available since 3.52 设置房间内某一远端用户在本地用户自建的空间音频坐标系中的发声位置和发声朝向，以实现本地用户预期的空间音频收听效果。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | uid | String | 用户 ID | | positionInfo | PositionInfo | 远端用户的空间音频位置信息。参看 [PositionInfo](70083#PositionInfo)。 | **返回值** - 0：成功。 - < 0：失败。 - -2：失败，原因是校验远端用户的三维朝向信息时，三个向量没有两两垂直。 **注意** - 该方法需在创建房间后调用。 - 调用此接口在本地进行的设定对其他用户的空间音频收听效果不会产生任何影响。 ### removeRemotePosition ```java int com.ss.bytertc.engine.audio.ISpatialAudio.removeRemotePosition(String uid) ``` > Available since 3.52 移除调用 [updateRemotePosition](#ISpatialAudio-updateremoteposition) 为某一远端用户设置的空间音频效果。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | uid | String | 远端用户 ID。 | **返回值** - 0：成功。 - < 0：失败。 ### removeAllRemotePosition ```java int com.ss.bytertc.engine.audio.ISpatialAudio.removeAllRemotePosition() ``` > Available since 3.52 移除调用 [updateRemotePosition](#ISpatialAudio-updateremoteposition) 为所有远端用户设置的空间音频效果。 **返回值** - 0：成功。 - < 0：失败。 # IVideoDeviceManager ```java public interface com.ss.bytertc.engine.video.IVideoDeviceManager ``` > Available since 3.56 主要用于枚举、设置视频采集设备 ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract List\ | [enumerateVideoCaptureDevices](#IVideoDeviceManager-enumeratevideocapturedevices) | | abstract int | [setVideoCaptureDevice](#IVideoDeviceManager-setvideocapturedevice) | ## 函数说明 ### enumerateVideoCaptureDevices ```java abstract List com.ss.bytertc.engine.video.IVideoDeviceManager.enumerateVideoCaptureDevices() ``` > Available since 3.56 获取当前系统内视频采集设备列表。 **返回值** 包含系统中所有视频采集设备的列表，参看 [VideoDeviceInfo](70083#VideoDeviceInfo)。 ### setVideoCaptureDevice ```java abstract int com.ss.bytertc.engine.video.IVideoDeviceManager.setVideoCaptureDevice(final String deviceId) ``` > Available since 3.56 设置当前视频采集设备 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | deviceId | final String | 视频设备 ID，可以通过 [enumerateVideoCaptureDevices](#IVideoDeviceManager-enumeratevideocapturedevices) 获取 | **返回值** - 0：方法调用成功 - !0：方法调用失败 # IVideoEffect ```java public abstract class com.ss.bytertc.engine.video.IVideoEffect ``` 高级视频特效，参看[集成指南](https://www.volcengine.com/docs/6348/114717)。 ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract int | [initCVResource](#IVideoEffect-initcvresource) | | abstract String | [getAuthMessage](#IVideoEffect-getauthmessage) | | abstract int | [enableVideoEffect](#IVideoEffect-enablevideoeffect) | | abstract int | [disableVideoEffect](#IVideoEffect-disablevideoeffect) | | abstract int | [setEffectNodes](#IVideoEffect-seteffectnodes) | | abstract int | [updateEffectNode](#IVideoEffect-updateeffectnode) | | abstract int | [setColorFilter](#IVideoEffect-setcolorfilter) | | abstract int | [setColorFilterIntensity](#IVideoEffect-setcolorfilterintensity) | | abstract int | [enableVirtualBackground](#IVideoEffect-enablevirtualbackground) | | abstract int | [disableVirtualBackground](#IVideoEffect-disablevirtualbackground) | | abstract int | [enableFaceDetection](#IVideoEffect-enablefacedetection) | | abstract int | [disableFaceDetection](#IVideoEffect-disablefacedetection) | ## 函数说明 ### initCVResource ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.initCVResource( String licenseFile, String algoModelDir ) ``` 检查视频特效证书，设置算法模型路径，并初始化特效模块。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | licenseFile | String | 证书文件的绝对路径，用于鉴权。 | | algoModelDir | String | 算法模型绝对路径，即存放特效 SDK 所有算法模型的目录。 | **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1002：特效 SDK 版本不兼容。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 **注意** 鉴权时，会检查 CV 服务端时间和本地设备的时间差异。你必须保证本地系统时间和实际时间一致。 ### getAuthMessage ```java public abstract String com.ss.bytertc.engine.video.IVideoEffect.getAuthMessage() ``` 从特效 SDK 获取授权消息，用于获取在线许可证。 **返回值** 授权消息字符串地址, 如果获取失败返回 nullptr。 **注意** - 使用视频特效的功能前，你必须获取特效 SDK 的在线许可证。 - 通过此接口获取授权消息后，参考 [在线授权说明](https://www.volcengine.com/docs/6705/102012)，自行实现获取在线许可证的业务逻辑。获取许可证后，你必须调用 [initCVResource](#IVideoEffect-initcvresource) 确认许可证有效。然后，你才可以使用 CV 功能。 ### enableVideoEffect ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.enableVideoEffect() ``` 开启高级美颜、滤镜等视频特效。 **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1001：特效 SDK 不支持该功能。 - –1002：特效 SDK 版本不兼容。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 **注意** - 调用本方法前，必须先调用 [initCVResource](#IVideoEffect-initcvresource) 进行初始化。 - 调用该方法后，特效不直接生效，你还需调用 [setEffectNodes](#IVideoEffect-seteffectnodes) 设置视频特效素材包或调用 [setColorFilter](#IVideoEffect-setcolorfilter) 设置滤镜。 - 调用 [disableVideoEffect](#IVideoEffect-disablevideoeffect) 关闭视频特效。 ### disableVideoEffect ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.disableVideoEffect() ``` 关闭视频特效。 **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1001：特效 SDK 不支持该功能。 - –1002：特效 SDK 版本不兼容。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 **注意** 调用 [enableVideoEffect](#IVideoEffect-enablevideoeffect) 开启视频特效。 ### setEffectNodes ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.setEffectNodes(List effectNodes) ``` 设置视频特效素材包。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectNodes | List\ | 特效素材包绝对路径数组。
要取消当前视频特效，将此参数设置为 null。 | **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1001：特效 SDK 不支持该功能。 - –1002：特效 SDK 版本不兼容。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 **注意** 调用本方法前，必须先调用 [enableVideoEffect](#IVideoEffect-enablevideoeffect)。 ### updateEffectNode ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.updateEffectNode( String effectNode, String key, float value ) ``` 设置特效强度。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectNode | String | 特效素材包绝对路径，参考[素材包结构说明](https://www.volcengine.com/docs/6705/102039)。 | | key | String | 需要设置的素材 key 名称，参考[素材 key 对应说明](https://www.volcengine.com/docs/6705/102041)。 | | value | float | 特效强度值，取值范围 [0,1]，超出范围时设置无效。 | **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1001：特效 SDK 不支持该功能。 - –1002：特效 SDK 版本不兼容。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### setColorFilter ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.setColorFilter(String filterRes) ``` 设置颜色滤镜。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | filterRes | String | 滤镜资源包绝对路径。 | **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1001：特效 SDK 不支持该功能。 - –1002：特效 SDK 版本不兼容。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 **注意** 调用 [setColorFilterIntensity](#IVideoEffect-setcolorfilterintensity) 设置已启用颜色滤镜的强度。设置强度为 0 时即关闭颜色滤镜。 ### setColorFilterIntensity ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.setColorFilterIntensity(float intensity) ``` 设置已启用颜色滤镜的强度。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | intensity | float | 滤镜强度。取值范围 [0,1]，超出范围时设置无效。
当设置滤镜强度为 0 时即关闭颜色滤镜。 | **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1001：特效 SDK 不支持该功能。 - –1002：特效 SDK 版本不兼容。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### enableVirtualBackground ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.enableVirtualBackground( String backgroundStickerRes, VirtualBackgroundSource source ) ``` 将摄像头采集画面中的人像背景替换为指定图片或纯色背景。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | backgroundStickerRes | String | 背景贴纸特效素材绝对路径。 | | source | VirtualBackgroundSource | 背景贴纸对象，参看 [VirtualBackgroundSource](70083#VirtualBackgroundSource)。 | **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1001：特效 SDK 不支持该功能。 - –1002：特效 SDK 版本不兼容。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 **注意** - 调用本方法前，必须先调用 [initCVResource](#IVideoEffect-initcvresource) 进行初始化。 - 调用 [disableVirtualBackground](#IVideoEffect-disablevirtualbackground) 关闭虚拟背景。 ### disableVirtualBackground ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.disableVirtualBackground() ``` 关闭虚拟背景。 **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1001：特效 SDK 不支持该功能。 - –1002：特效 SDK 版本不兼容。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 **注意** 调用 [enableVirtualBackground](#IVideoEffect-enablevirtualbackground) 开启虚拟背景后，可以调用此接口关闭虚拟背景。 ### enableFaceDetection ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.enableFaceDetection( IFaceDetectionObserver observer, int intervalMs, String faceModelPath ) ``` 开启人脸识别功能，并设置人脸检测结果回调观察者。此观察者后，你会周期性收到 [onFaceDetectResult](70081#IFaceDetectionObserver-onfacedetectresult) 回调。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | observer | IFaceDetectionObserver | 人脸检测结果回调观察者，参看 [IFaceDetectionObserver](70081#IFaceDetectionObserver)。 | | intervalMs | int | 两次回调之间的最小时间间隔，必须大于 0，单位为毫秒。实际收到回调的时间间隔大于 interval_ms，小于 interval_ms+视频采集帧间隔。 | | faceModelPath | String | 人脸检测算法模型文件路径，一般为 ttfacemodel 文件夹中 tt_face_vXXX.model 文件的绝对路径。 | **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1001：特效 SDK 不支持该功能。 - –1002：特效 SDK 版本不兼容。 - -1004：初始化中，初始化完成后启动此功能。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 ### disableFaceDetection ```java public abstract int com.ss.bytertc.engine.video.IVideoEffect.disableFaceDetection() ``` 关闭人脸识别功能。 **返回值** - 0：调用成功。 - –1000：未集成特效 SDK。 - –1001：特效 SDK 不支持该功能。 - –1002：特效 SDK 版本不兼容。 - < 0：调用失败，错误码对应具体描述参看 [错误码表](https://www.volcengine.com/docs/6705/102042)。 # IRTCAudioDeviceManager ```java public interface com.ss.bytertc.engine.IRTCAudioDeviceManager ``` IRTCAudioDeviceManager 接口 ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract int | [startAudioPlaybackDeviceTest](#IRTCAudioDeviceManager-startaudioplaybackdevicetest) | | abstract int | [stopAudioPlaybackDeviceTest](#IRTCAudioDeviceManager-stopaudioplaybackdevicetest) | | abstract int | [startAudioDeviceRecordTest](#IRTCAudioDeviceManager-startaudiodevicerecordtest) | | abstract int | [stopAudioDeviceRecordAndPlayTest](#IRTCAudioDeviceManager-stopaudiodevicerecordandplaytest) | | abstract int | [stopAudioDevicePlayTest](#IRTCAudioDeviceManager-stopaudiodeviceplaytest) | ## 函数说明 ### startAudioPlaybackDeviceTest ```java abstract int com.ss.bytertc.engine.IRTCAudioDeviceManager.startAudioPlaybackDeviceTest( String testAudioFilePath, int interval ) ``` 启动音频播放设备检测。测试启动后，循环播放指定的音频文件，同时将通过 `onAudioPlaybackDeviceTestVolume` 回调播放时的音量信息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | testAudioFilePath | String | 指定播放设备检测的音频文件网络地址。支持的格式包括 mp3，aac，m4a，3gp 和 wav。 | | interval | int | 设置 `onAudioPlaybackDeviceTestVolume` 音量回调的时间间隔，推荐设置为 200 毫秒或以上。单位为毫秒。最小值为 10 毫秒。 | **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 **注意** - 该方法可在进房前和进房后调用，不可与其它音频设备测试功能同时应用。 - 调用 [stopAudioPlaybackDeviceTest](#IRTCAudioDeviceManager-stopaudioplaybackdevicetest) 可以停止测试。 ### stopAudioPlaybackDeviceTest ```java abstract int com.ss.bytertc.engine.IRTCAudioDeviceManager.stopAudioPlaybackDeviceTest() ``` 停止音频播放测试。 **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 **注意** 调用 [startAudioPlaybackDeviceTest](#IRTCAudioDeviceManager-startaudioplaybackdevicetest) 后，调用本方法停止测试。 ### startAudioDeviceRecordTest ```java abstract int com.ss.bytertc.engine.IRTCAudioDeviceManager.startAudioDeviceRecordTest(int interval) ``` 开始音频采集设备和音频播放设备测试。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | interval | int | 测试中会收到 `enableAudioPropertiesReport` 回调，本参数指定了该周期回调的时间间隔，单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒。 | **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 **注意** - 该方法在进房前后均可调用。且不可与其它音频设备测试功能同时应用。 - 调用本接口 30 s 后，采集自动停止，并开始播放采集到的声音。录音播放完毕后，设备测试流程自动结束。你也可以在 30 s 内调用 [stopAudioDeviceRecordAndPlayTest](#IRTCAudioDeviceManager-stopaudiodevicerecordandplaytest) 来停止采集并开始播放此前采集到的声音。 - 调用 [stopAudioDevicePlayTest](#IRTCAudioDeviceManager-stopaudiodeviceplaytest) 可以停止音频设备采集和播放测试。 - 你不应在测试过程中，调用 `enableAudioPropertiesReport` 注册音量提示回调。 - 该方法仅在本地进行音频设备测试，不涉及网络连接。 ### stopAudioDeviceRecordAndPlayTest ```java abstract int com.ss.bytertc.engine.IRTCAudioDeviceManager.stopAudioDeviceRecordAndPlayTest() ``` 停止采集本地音频，并开始播放采集到的声音。录音播放完毕后，设备测试流程结束。调用 [startAudioDeviceRecordTest](#IRTCAudioDeviceManager-startaudiodevicerecordtest) 30 s 内调用本接口来停止采集并开始播放此前采集到的声音。 **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 **注意** 调用本接口开始播放录音后，可以在播放过程中调用 [stopAudioDevicePlayTest](#IRTCAudioDeviceManager-stopaudiodeviceplaytest) 停止播放。 ### stopAudioDevicePlayTest ```java abstract int com.ss.bytertc.engine.IRTCAudioDeviceManager.stopAudioDevicePlayTest() ``` 停止由调用 [startAudioDeviceRecordTest](#IRTCAudioDeviceManager-startaudiodevicerecordtest) 开始的音频播放设备测试。在音频播放设备测试自动结束前，可调用本接口停止音频采集与播放测试。 **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 # RTCRoom ```java public abstract class com.ss.bytertc.engine.RTCRoom ``` RTC 房间类 ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract void | [destroy](#RTCRoom-destroy) | | abstract int | [joinRoom](#RTCRoom-joinroom) | | abstract int | [setRTCRoomEventHandler](#RTCRoom-setrtcroomeventhandler) | | abstract int | [setUserVisibility](#RTCRoom-setuservisibility) | | abstract int | [setMultiDeviceAVSync](#RTCRoom-setmultideviceavsync) | | abstract int | [setRemoteSimulcastStreamType](#RTCRoom-setremotesimulcaststreamtype) | | abstract int | [publishStreamVideo](#RTCRoom-publishstreamvideo) | | abstract int | [publishStreamAudio](#RTCRoom-publishstreamaudio) | | abstract int | [subscribeStreamVideo](#RTCRoom-subscribestreamvideo) | | abstract int | [subscribeStreamAudio](#RTCRoom-subscribestreamaudio) | | abstract int | [subscribeAllStreamsVideo](#RTCRoom-subscribeallstreamsvideo) | | abstract int | [subscribeAllStreamsAudio](#RTCRoom-subscribeallstreamsaudio) | | abstract int | [pauseAllSubscribedStreamVideo](#RTCRoom-pauseallsubscribedstreamvideo) | | abstract int | [pauseAllSubscribedStreamAudio](#RTCRoom-pauseallsubscribedstreamaudio) | | abstract int | [resumeAllSubscribedStreamVideo](#RTCRoom-resumeallsubscribedstreamvideo) | | abstract int | [resumeAllSubscribedStreamAudio](#RTCRoom-resumeallsubscribedstreamaudio) | | abstract int | [startForwardStreamToRooms](#RTCRoom-startforwardstreamtorooms) | | abstract int | [updateForwardStreamToRooms](#RTCRoom-updateforwardstreamtorooms) | | abstract int | [stopForwardStreamToRooms](#RTCRoom-stopforwardstreamtorooms) | | abstract int | [pauseForwardStreamToAllRooms](#RTCRoom-pauseforwardstreamtoallrooms) | | abstract int | [resumeForwardStreamToAllRooms](#RTCRoom-resumeforwardstreamtoallrooms) | | abstract IRangeAudio | [getRangeAudio](#RTCRoom-getrangeaudio) | | abstract ISpatialAudio | [getSpatialAudio](#RTCRoom-getspatialaudio) | | abstract int | [setRemoteRoomAudioPlaybackVolume](#RTCRoom-setremoteroomaudioplaybackvolume) | | abstract int | [setAudioSelectionConfig](#RTCRoom-setaudioselectionconfig) | | abstract long | [setRoomExtraInfo](#RTCRoom-setroomextrainfo) | | abstract int | [setStreamExtraInfo](#RTCRoom-setstreamextrainfo) | | abstract int | [setRemoteVideoConfig](#RTCRoom-setremotevideoconfig) | | abstract int | [startSubtitle](#RTCRoom-startsubtitle) | | abstract int | [stopSubtitle](#RTCRoom-stopsubtitle) | | abstract String | [getRoomId](#RTCRoom-getroomid) | | abstract String | [getCallId](#RTCRoom-getcallid) | ## 函数说明 ### destroy ```java public abstract void com.ss.bytertc.engine.RTCRoom.destroy() ``` 退出并销毁调用 [createRTCRoom](#RTCEngine-creatertcroom) 所创建的房间实例。 ### joinRoom ```java public abstract int com.ss.bytertc.engine.RTCRoom.joinRoom( String token, UserInfo userInfo, boolean userVisibility, RTCRoomConfig roomConfig ) ``` 加入 RTC 房间。调用 [createRTCRoom](#RTCEngine-creatertcroom) 创建房间后，调用此方法加入房间，同房间内其他用户进行音视频通话。 > 用户（包括后端机器人）成功进入 RTC 房间后便开始计费。即使房间内只有 1 个用户，也会计算音频计费时长。具体计费说明，请参见[音视频通话计费](69871)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | String | 动态密钥。用于对进房用户进行鉴权验证。
进入房间需要携带 Token。测试时可使用控制台生成临时 Token，正式上线需要使用密钥 SDK 在你的服务端生成并下发 Token。Token 有效期及生成方式参看[使用 Token 完成鉴权](70121)。
使用不同 AppID 的 App 是不能互通的。
请务必保证生成 Token 使用的 AppID 和创建引擎时使用的 AppID 相同，否则会导致加入房间失败。 | | userInfo | UserInfo | 用户信息。参看 [UserInfo](70083#UserInfo)。 | | userVisibility | boolean | 用户可见性。建议在进房时将用户可见性都设置为 `false`，并在用户需要发送音视频流时再通过 [setUserVisibility](#RTCRoom-setuservisibility) 设置为 `true`。从而避免因房间内用户达到数量上限所导致的进房失败。默认情况下，一个 RTC 房间最多同时容纳 50 名可见用户，其中最多 30 人可同时上麦，更多信息参看[用户和媒体流上限](https://www.volcengine.com/docs/6348/257549)。 | | roomConfig | RTCRoomConfig | 房间参数配置，设置房间模式以及是否自动发布或订阅流。具体配置模式参看 [RTCRoomConfig](70083#RTCRoomConfig)。 | **返回值** - 0：方法调用成功。 - 0：成功。触发以下回调： - 本端收到房间状态通知 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged) 回调。 - 本端收到本地流发布状态通知 [onVideoPublishStateChanged](70081#IRTCRoomEventHandler-onvideopublishstatechanged)、[onAudioPublishStateChanged](70081#IRTCRoomEventHandler-onaudiopublishstatechanged) 回调 - 本端收到流订阅状态通知 [onVideoSubscribeStateChanged](70081#IRTCRoomEventHandler-onvideosubscribestatechanged)、[onAudioSubscribeStateChanged](70081#IRTCRoomEventHandler-onaudiosubscribestatechanged) 回调。 - 本端收到房间内已发布流的通知 [onUserPublishStreamVideo](70081#IRTCRoomEventHandler-onuserpublishstreamvideo)、[onUserPublishStreamAudio](70081#IRTCRoomEventHandler-onuserpublishstreamaudio) 回调。 - 如果本端用户为可见用户，房间内其他用户收到 [onUserJoined](70081#IRTCRoomEventHandler-onuserjoined) 回调通知。 - -1：roomID / userInfo.uid 包含了无效的参数。 - -2：已经在房间内。接口调用成功后，只要收到返回值为 0 ，且未调用 [leaveRoom](#RTSRoom-leaveroom) 成功，则再次调用进房接口时，无论填写的房间 ID 和用户 ID 是否重复，均触发此返回值。调用失败时，具体失败原因会通过 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged) 回调告知。 **注意** - 该接口必须在调用 [setAudioScenario](70080#RTCEngine-setaudioscenario) 之后调用。 - 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后进房的用户会将先进房的用户踢出房间，并且先进房的用户会收到 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged) 回调通知，错误类型详见 [ERROR_CODE_DUPLICATE_LOGIN](70082#ErrorCode-error_code_duplicate_login)。 - 房间内不可见用户的容量远远大于可见用户，而且用户默认可见，因此对于不参与互动的用户，你需要调用 [setUserVisibility](#RTCRoom-setuservisibility) 更改为不可见用户。从而避免因房间内用户达到数量上限所导致的进房失败。默认情况下，一个 RTC 房间最多同时容纳 50 名可见用户，其中最多 30 人可同时上麦，更多信息参看[用户和媒体流上限](https://www.volcengine.com/docs/6348/257549)。 - 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，并触发 [onConnectionStateChanged](70081#IRTCEngineEventHandler-onconnectionstatechanged) 回调。此时 SDK 会自动重试，直到成功重连。重连成功后，本地会收到 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged) 回调通知；如果加入房间的用户是可见用户，远端用户会收到 [onUserJoined](70081#IRTCRoomEventHandler-onuserjoined) 回调通知。 ### setRTCRoomEventHandler ```java public abstract int com.ss.bytertc.engine.RTCRoom.setRTCRoomEventHandler(IRTCRoomEventHandler rtcRoomEventHandler) ``` 通过设置 [RTCRoom](#RTCRoom) 对象的事件句柄，监听此对象对应的回调事件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | rtcRoomEventHandler | IRTCRoomEventHandler | 参看 [IRTCRoomEventHandler](70081#IRTCRoomEventHandler) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### setUserVisibility ```java public abstract int com.ss.bytertc.engine.RTCRoom.setUserVisibility(boolean enable) ``` 设置用户可见性。未调用该接口前，本地用户默认对他人可见。默认情况下，一个 RTC 房间最多同时容纳 50 名可见用户，最多 30 人可同时上麦。更多信息参看[用户和媒体流上限](https://www.volcengine.com/docs/6348/257549)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 设置用户是否对房间内其他用户可见：

true：可见，用户可以在房间内发布音视频流，房间中的其他用户将收到用户的行为通知，例如进房、开启视频采集和退房。
false：不可见，用户不可以在房间内发布音视频流，房间中的其他用户不会收到用户的行为通知，例如进房、开启视频采集和退房。

| **返回值** - 0：调用成功。 - < 0：调用失败。参看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。设置用户可见性，会收到设置成功/失败回调 [onUserVisibilityChanged](70081#IRTCRoomEventHandler-onuservisibilitychanged)。（v3.54 新增） - 在加入房间前设置用户可见性，若设置的可见性与默认值不同，将在加入房间时触发本回调。 - 在加入房间后设置用户可见性，若可见性前后不同，会触发本回调。 - 在断网重连后，若可见性发生改变，会触发本回调。 **注意** - 在加入房间前后，用户均可调用此方法设置用户可见性。 - 在房间内，调用此方法成功切换用户可见性后，房间内其他用户会收到相应的回调。 - 从可见换至不可见时，房间内其他用户会收到 [onUserLeave](70081#IRTCRoomEventHandler-onuserleave)。 - 从不可见切换至可见时，房间内其他用户会收到 [onUserJoined](70081#IRTCRoomEventHandler-onuserjoined)。 - 若调用该方法将可见性设为 `false`，此时尝试发布流会收到 `WARNING_CODE_PUBLISH_STREAM_FORBIDEN` 警告。 ### setMultiDeviceAVSync ```java public abstract int com.ss.bytertc.engine.RTCRoom.setMultiDeviceAVSync(String audioUserId) ``` 设置发流端音画同步。当同一用户同时使用两个通话设备分别采集发送音频和视频时，有可能会因两个设备所处的网络环境不一致而导致发布的流不同步，此时你可以在视频发送端调用该接口，SDK 会根据音频流的时间戳自动校准视频流，以保证接收端听到音频和看到视频在时间上的同步性。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audioUserId | String | 音频发送端的用户 ID，将该参数设为空则可解除当前音视频的同步关系。 | **返回值** - 0：调用成功。调用该接口后音画同步状态发生改变时，你会收到 [onAVSyncStateChange](70081#IRTCRoomEventHandler-onavsyncstatechange) 回调。 - < 0：调用失败。你也可以通过监听 [onAVSyncEvent](70081#IRTCRoomEventHandler-onavsyncevent) 获取错误详情。同一 RTC 房间内允许存在多个音视频同步关系，但需注意单个音频源不支持与多个视频源同时同步。 **注意** - 该方法在进房前后均可调用。 - 进行音画同步的音频发布用户 ID 和视频发布用户 ID 须在同一个 RTC 房间内。 - 如需更换同步音频源，再次调用该接口传入新的 `audioUserId` 即可；如需更换同步视频源，需先解除当前的同步关系，后在新视频源端开启同步。 ### setRemoteSimulcastStreamType ```java public abstract int com.ss.bytertc.engine.RTCRoom.setRemoteSimulcastStreamType( String streamId, SimulcastStreamType streamType ) ``` > Available since 3.60. 设置期望订阅的远端视频流类型。比如大流、中流、小流等。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 目标要订阅的远端视频流 ID。 | | streamType | SimulcastStreamType | 远端视频流类型，参看 [SimulcastStreamType](70083#SimulcastStreamType)。 | **返回值** 方法调用结果： - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** - 若使用 342 及以前版本的 SDK，调用该方法前请联系技术支持人员开启按需订阅功能。 - 该方法仅在发布端调用 [setLocalSimulcastMode](#RTCEngine-setlocalsimulcastmode) 开启了发送多路视频流的情况下生效。 - 若发布端开启了推送多路流功能，但订阅端不对流参数进行设置，则默认接受发送端设置的分辨率最大的一路视频流。该方法可在进房后调用。 ### publishStreamVideo ```java public abstract int com.ss.bytertc.engine.RTCRoom.publishStreamVideo(boolean publish) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `publishStream`、`unpublishStream` 、`publishScreen` 和 `unpublishScreen` 方法来实现下述功能。如果你如果你已升级至 3.60 及以上版本，并且仍在使用这两个方法，请迁移到此接口。发布/取消发布视频流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | publish | boolean | 是否发布视频流。

`true`：发布。
`false`：取消发布。

| **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 如果你已经在用户进房时通过调用 [joinRoom](#RTCRoom-joinroom) 成功选择了自动发布，则无需再调用本接口。 - 调用 [setUserVisibility](#RTCRoom-setuservisibility) 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布摄像头视频流。 - 如果你需要发布麦克风采集到的音频流，调用 [publishStreamAudio](#RTCRoom-publishstreamaudio)。 - 如果你需要向多个房间发布流，调用 [startForwardStreamToRooms](#RTCRoom-startforwardstreamtorooms)。 - 调用此方法后，房间中的所有远端用户会收到 [onUserPublishStreamVideo](70081#IRTCRoomEventHandler-onuserpublishstreamvideo) 回调通知，订阅了视频流的远端用户会收到 [onFirstRemoteVideoFrameDecoded](70081#IRTCEngineEventHandler-onfirstremotevideoframedecoded) 回调。 ### publishStreamAudio ```java public abstract int com.ss.bytertc.engine.RTCRoom.publishStreamAudio(boolean publish) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `publishStream`、`unpublishStream` 、`publishScreen` 和 `unpublishScreen` 方法来实现下述功能。如果你如果你已升级至 3.60 及以上版本，并且仍在使用这两个方法，请迁移到此接口。发布/取消发布音频流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | publish | boolean | 是否发布音频流。

`true`：发布。
`false`：取消发布。

| **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 如果你已经在用户进房时通过调用 [joinRoom](#RTCRoom-joinroom) 成功选择了自动发布，则无需再调用本接口。 - 调用 [setUserVisibility](#RTCRoom-setuservisibility) 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布音频流。 - 如果你需要发布摄像头采集到的视频流，调用 [publishStreamVideo](#RTCRoom-publishstreamvideo)。 - 如果你需要向多个房间发布流，调用 [startForwardStreamToRooms](#RTCRoom-startforwardstreamtorooms)。 - 调用此方法后，房间中的所有远端用户会收到 [onUserPublishStreamAudio](70081#IRTCRoomEventHandler-onuserpublishstreamaudio) 回调通知，其中成功收到了音频流的远端用户会收到 [onFirstRemoteAudioFrame](70081#IRTCEngineEventHandler-onfirstremoteaudioframe) 回调。 ### subscribeStreamVideo ```java public abstract int com.ss.bytertc.engine.RTCRoom.subscribeStreamVideo( String streamId, boolean subscribe ) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `subscribeStream`, `unsubscribeStream`, `subscribeScreen` 和 `unsubscribeScreen` 方法来实现下述功能。如果你已升级至 3.60 及以上版本，且仍在使用这两个方法，请迁移至该接口。订阅/取消订阅房间内指定的远端视频流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 目标远端视频流 ID。 | | subscribe | boolean | 是否订阅该视频流。

`true`：订阅。
`false`：取消订阅。

| **返回值** 方法调用结果： - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** - 在调用本接口时已经订阅该远端流（手动订阅或自动订阅），则将根据本次传入的参数，更新订阅配置。 - 你必须先通过 [onUserPublishStreamVideo](70081#IRTCRoomEventHandler-onuserpublishstreamvideo) 回调获取当前房间里的远端摄像头流信息，然后调用本方法按需订阅。 - 调用该方法后，你会收到 [onVideoSubscribeStateChanged](70081#IRTCRoomEventHandler-onvideosubscribestatechanged) 通知方法调用结果。 - 成功订阅远端用户的媒体流后，订阅关系将持续到调用 [subscribeStreamVideo](#RTCRoom-subscribestreamvideo) 取消订阅或本端用户退房。 - 关于其他调用异常，你会收到 [onVideoSubscribeStateChanged](70081#IRTCRoomEventHandler-onvideosubscribestatechanged) 回调通知，具体异常原因参看 [SubscribeStateChangeReason](70083#SubscribeStateChangeReason)。 ### subscribeStreamAudio ```java public abstract int com.ss.bytertc.engine.RTCRoom.subscribeStreamAudio( String streamId, boolean subscribe ) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `subscribeStream`, `unsubscribeStream`, `subscribeScreen` 和 `unsubscribeScreen` 方法来实现下述功能。如果你已升级至 3.60 及以上版本，且仍在使用这两个方法，请迁移至该接口。订阅/取消订阅房间内指定的远端音频流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 目标远端音频流 ID。 | | subscribe | boolean | 是否要订阅指定的远端音频流。

`true`：订阅。
`false`：取消订阅。

| **返回值** 方法调用结果： - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** - 若当前用户在调用本接口时已经订阅该远端音频流（手动订阅或自动订阅），则将根据本次传入的参数，更新订阅配置。 - 你必须先通过 [onUserPublishStreamAudio](70081#IRTCRoomEventHandler-onuserpublishstreamaudio) 回调获取当前房间里的远端麦克风流信息，然后调用本方法按需订阅。 - 调用该方法后，你会收到 [onAudioSubscribeStateChanged](70081#IRTCRoomEventHandler-onaudiosubscribestatechanged) 通知方法调用结果。 - 成功订阅远端用户的媒体流后，订阅关系将持续到调用 [subscribeStreamAudio](#RTCRoom-subscribestreamaudio) 取消订阅或本端用户退房。 - 关于其他调用异常，你会收到 [onAudioSubscribeStateChanged](70081#IRTCRoomEventHandler-onaudiosubscribestatechanged) 回调通知，具体异常原因参看 [SubscribeStateChangeReason](70083#SubscribeStateChangeReason)。 ### subscribeAllStreamsVideo ```java public abstract int com.ss.bytertc.engine.RTCRoom.subscribeAllStreamsVideo(boolean subscribe) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `subscribeAllStreams` 和 `unsubscribeAllStreams` 方法来实现下述功能。如果你已升级至 3.60 及以上版本，且仍在使用这两个方法，请迁移至该接口。订阅/取消订阅房间内所有远端视频流（通过摄像头采集的）。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | subscribe | boolean | 是否订阅所有远端视频流。

`true`：订阅。
`false`：取消订阅。

| **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 多次调用订阅接口时，将根据末次调用接口和传入的参数，更新订阅配置：[subscribeStreamVideo](#RTCRoom-subscribestreamvideo)、[subscribeStreamAudio](#RTCRoom-subscribestreamaudio)。 - 开启音频选路后，如果房间内的媒体流超过上限，建议通过调用单流订阅接口逐一指定需要订阅的媒体流。 - 调用该方法后，你会收到 [onVideoSubscribeStateChanged](70081#IRTCRoomEventHandler-onvideosubscribestatechanged)、[onAudioSubscribeStateChanged](70081#IRTCRoomEventHandler-onaudiosubscribestatechanged) 通知方法调用结果，包含异常原因。 - 成功订阅远端用户的媒体流后，订阅关系将持续到调用 [subscribeStreamVideo](#RTCRoom-subscribestreamvideo)、[subscribeStreamAudio](#RTCRoom-subscribestreamaudio) 取消订阅或本端用户退房。 ### subscribeAllStreamsAudio ```java public abstract int com.ss.bytertc.engine.RTCRoom.subscribeAllStreamsAudio(boolean subscribe) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `subscribeAllStreams` 和 `unsubscribeAllStreams` 方法，用于下面的功能。如果您已升级到 3.60 或更高版本，并且仍在使用这些方法，请尽快迁移到该接口。订阅或取消订阅所有远端音频流（通过麦克风采集的）。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | subscribe | boolean | 是否订阅所有远端音频流：

`true`：订阅。
`false`：取消订阅。

| **返回值** 方法调用结果： - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 多次调用订阅接口时，将根据末次调用接口和传入的参数，更新订阅配置：[subscribeStreamVideo](#RTCRoom-subscribestreamvideo)、[subscribeStreamAudio](#RTCRoom-subscribestreamaudio)。 - 开启音频选路后，如果房间内的媒体流超过上限，建议通过调用单流订阅接口逐一指定需要订阅的媒体流。 - 调用该方法后，你会收到 [onVideoSubscribeStateChanged](70081#IRTCRoomEventHandler-onvideosubscribestatechanged)、[onAudioSubscribeStateChanged](70081#IRTCRoomEventHandler-onaudiosubscribestatechanged) 通知方法调用结果，包含异常原因。 - 成功订阅远端用户的媒体流后，订阅关系将持续到调用 [subscribeStreamVideo](#RTCRoom-subscribestreamvideo)、[subscribeStreamAudio](#RTCRoom-subscribestreamaudio) 取消订阅或本端用户退房。 ### pauseAllSubscribedStreamVideo ```java public abstract int com.ss.bytertc.engine.RTCRoom.pauseAllSubscribedStreamVideo() ``` > Available since 3.60. 自 3.60 起，该接口替代了 `pauseAllSubscribedStream` 方法来实现下述功能。如果你已升级至 3.60 及以上版本，且仍在使用该方法，请迁移至该接口。暂停接收所有远端视频流。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法仅暂停远端流的接收，并不影响远端流的采集和发送； - 该方法不改变用户的订阅状态以及订阅流的属性。 - 若想恢复接收远端流，需调用 [resumeAllSubscribedStreamVideo](#RTCRoom-resumeallsubscribedstreamvideo)。 - 多房间场景下，仅暂停接收发布在当前所在房间的流。 ### pauseAllSubscribedStreamAudio ```java public abstract int com.ss.bytertc.engine.RTCRoom.pauseAllSubscribedStreamAudio() ``` > Available since 3.60. 自 3.60 起，该接口替代了 `pauseAllSubscribedStream` 方法来实现下述功能。如果你已升级至 3.60 及以上版本，且仍在使用该方法，请迁移至该接口。暂停接收所有远端音频流。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法仅暂停远端流的接收，并不影响远端流的采集和发送； - 该方法不改变用户的订阅状态以及订阅流的属性。 - 若想恢复接收远端流，需调用 [resumeAllSubscribedStreamVideo](#RTCRoom-resumeallsubscribedstreamvideo)。 - 多房间场景下，仅暂停接收发布在当前所在房间的流。 ### resumeAllSubscribedStreamVideo ```java public abstract int com.ss.bytertc.engine.RTCRoom.resumeAllSubscribedStreamVideo() ``` > Available since 3.60. 自 3.60 起，该接口替代了 `resumeAllSubscribedStream` 方法来实现下述功能。如果你已升级至 3.60 及以上版本，且仍在使用该方法，请迁移至该接口。恢复接收所有远端视频流。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法仅恢复远端流的接收，并不影响远端流的采集和发送； - 该方法不改变用户的订阅状态以及订阅流的属性。 ### resumeAllSubscribedStreamAudio ```java public abstract int com.ss.bytertc.engine.RTCRoom.resumeAllSubscribedStreamAudio() ``` > Available since 3.60. 自 3.60 起，该接口替代了 `resumeAllSubscribedStream` 方法来实现下述功能。如果你已升级至 3.60 及以上版本，且仍在使用该方法，请迁移至该接口。恢复接收所有远端音频流。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法仅恢复远端流的接收，并不影响远端流的采集和发送； - 该方法不改变用户的订阅状态以及订阅流的属性。 ### startForwardStreamToRooms ```java public abstract int com.ss.bytertc.engine.RTCRoom.startForwardStreamToRooms(List forwardStreamInfos) ``` 开始跨房间转发媒体流。在调用 [joinRoom](#RTCRoom-joinroom) 后调用本接口，实现向多个房间转发媒体流，适用于跨房间连麦等场景。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | forwardStreamInfos | List\ | 跨房间媒体流转发指定房间的信息。参看 [ForwardStreamInfo](70083#ForwardStreamInfo)。 | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用本方法后，将在本端触发 [onForwardStreamStateChanged](70081#IRTCRoomEventHandler-onforwardstreamstatechanged) 回调。 - 调用本方法后，你可以通过监听 [onForwardStreamEvent](70081#IRTCRoomEventHandler-onforwardstreamevent) 回调来获取各个目标房间在转发媒体流过程中的相关事件。 - 开始转发后，目标房间中的用户将接收到本地用户进房 [onUserJoined](70081#IRTCRoomEventHandler-onuserjoined) 和发流 [onUserPublishStreamVideo](70081#IRTCRoomEventHandler-onuserpublishstreamvideo)、[onUserPublishStreamAudio](70081#IRTCRoomEventHandler-onuserpublishstreamaudio) 回调。 - 调用本方法后，可以调用 [updateForwardStreamToRooms](#RTCRoom-updateforwardstreamtorooms) 更新目标房间信息，例如，增加或减少目标房间等。 - 调用本方法后，可以调用 [stopForwardStreamToRooms](#RTCRoom-stopforwardstreamtorooms) 停止向所有房间转发媒体流。 - 调用本方法后，可以调用 [pauseForwardStreamToAllRooms](#RTCRoom-pauseforwardstreamtoallrooms) 暂停向所有房间转发媒体流。 ### updateForwardStreamToRooms ```java public abstract int com.ss.bytertc.engine.RTCRoom.updateForwardStreamToRooms(List forwardStreamInfos) ``` 更新跨房间媒体流转发信息。通过 [startForwardStreamToRooms](#RTCRoom-startforwardstreamtorooms) 发起媒体流转发后，可调用本方法增加或者减少目标房间，或更新房间密钥。调用本方法增加或删减房间后，将在本端触发 [onForwardStreamStateChanged](70081#IRTCRoomEventHandler-onforwardstreamstatechanged) 回调，包含发生了变动的目标房间中媒体流转发状态。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | forwardStreamInfos | List\ | 跨房间媒体流转发目标房间信息。参看 [ForwardStreamInfo](70083#ForwardStreamInfo)。 | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 增加或删减目标房间后，新增目标房间中的用户将接收到本地用户进房 [onUserJoined](70081#IRTCRoomEventHandler-onuserjoined) 和发布 [onUserPublishStreamVideo](70081#IRTCRoomEventHandler-onuserpublishstreamvideo)、[onUserPublishStreamAudio](70081#IRTCRoomEventHandler-onuserpublishstreamaudio) 回调。 ### stopForwardStreamToRooms ```java public abstract int com.ss.bytertc.engine.RTCRoom.stopForwardStreamToRooms() ``` 停止跨房间媒体流转发。通过 [startForwardStreamToRooms](#RTCRoom-startforwardstreamtorooms) 发起媒体流转发后，可调用本方法停止向所有目标房间转发媒体流。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用本方法后，将在本端触发 [onForwardStreamStateChanged](70081#IRTCRoomEventHandler-onforwardstreamstatechanged) 回调。 - 调用本方法后，原目标房间中的用户将接收到本地用户停止发布 [onUserPublishStreamVideo](70081#IRTCRoomEventHandler-onuserpublishstreamvideo)、[onUserPublishStreamAudio](70081#IRTCRoomEventHandler-onuserpublishstreamaudio) 回调和退房 [onUserLeave](70081#IRTCRoomEventHandler-onuserleave) 的回调。 - 如果需要停止向指定的房间转发媒体流，请调用 [updateForwardStreamToRooms](#RTCRoom-updateforwardstreamtorooms) 更新房间信息。 - 如果需要暂停转发，请调用 [pauseForwardStreamToAllRooms](#RTCRoom-pauseforwardstreamtoallrooms)，并在之后随时调用 [resumeForwardStreamToAllRooms](#RTCRoom-resumeforwardstreamtoallrooms) 快速恢复转发。 ### pauseForwardStreamToAllRooms ```java public abstract int com.ss.bytertc.engine.RTCRoom.pauseForwardStreamToAllRooms() ``` 暂停跨房间媒体流转发。通过 [startForwardStreamToRooms](#RTCRoom-startforwardstreamtorooms) 发起媒体流转发后，可调用本方法暂停向所有目标房间转发媒体流。调用本方法暂停向所有目标房间转发后，你可以随时调用 [resumeForwardStreamToAllRooms](#RTCRoom-resumeforwardstreamtoallrooms) 快速恢复转发。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 调用本方法后，目标房间中的用户将接收到本地用户停止发布 [onUserPublishStreamVideo](70081#IRTCRoomEventHandler-onuserpublishstreamvideo)、[onUserPublishStreamAudio](70081#IRTCRoomEventHandler-onuserpublishstreamaudio) 回调和退房 [onUserLeave](70081#IRTCRoomEventHandler-onuserleave) 的回调。 ### resumeForwardStreamToAllRooms ```java public abstract int com.ss.bytertc.engine.RTCRoom.resumeForwardStreamToAllRooms() ``` 恢复跨房间媒体流转发。调用 [pauseForwardStreamToAllRooms](#RTCRoom-pauseforwardstreamtoallrooms) 暂停转发之后，调用本方法恢复向所有目标房间转发媒体流。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 目标房间中的用户将接收到本地用户进房 [onUserJoined](70081#IRTCRoomEventHandler-onuserjoined) 和发布 [onUserPublishStreamVideo](70081#IRTCRoomEventHandler-onuserpublishstreamvideo)、[onUserPublishStreamAudio](70081#IRTCRoomEventHandler-onuserpublishstreamaudio) 回调的回调。 ### getRangeAudio ```java public abstract IRangeAudio com.ss.bytertc.engine.RTCRoom.getRangeAudio() ``` 获取范围语音接口实例。 **返回值** 方法调用结果： - IRangeAudio：成功，返回一个 [IRangeAudio](#IRangeAudio) 实例。 - null：失败，当前 SDK 不支持范围语音功能。 **注意** 首次调用该方法须在创建房间后、加入房间前。范围语音相关 API 和调用时序详见[范围语音](https://www.volcengine.com/docs/6348/114727)。 ### getSpatialAudio ```java public abstract ISpatialAudio com.ss.bytertc.engine.RTCRoom.getSpatialAudio() ``` 获取空间音频接口实例。 **返回值** 空间音频管理接口实例。如果返回 NULL，则表示不支持空间音频，详见 [ISpatialAudio](#ISpatialAudio) 。 **注意** - 首次调用该方法须在创建房间后、加入房间前。空间音频相关 API 和调用时序详见[空间音频](https://www.volcengine.com/docs/6348/93903)。 - 只有在使用支持真双声道播放的设备时，才能开启空间音频效果； - 在网络状况不佳的情况下，即使开启了这一功能，也不会产生空间音频效果； - 机型性能不足可能会导致音频卡顿，使用低端机时，不建议开启空间音频效果； - 空间音频效果在启用服务端选路功能时，不生效。 ### setRemoteRoomAudioPlaybackVolume ```java public abstract int com.ss.bytertc.engine.RTCRoom.setRemoteRoomAudioPlaybackVolume(int volume) ``` 调节某个房间内所有远端用户的音频播放音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 音频播放音量和原始音量的比值，范围是 [0, 400]，单位为 \%，自带溢出保护。
为保证更好的通话质量，建议将 volume 值设为 [0,100]。

0：静音
100：原始音量，默认值
400：最大可为原始音量的 4 倍(自带溢出保护)

| **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 假设某远端用户 A 始终在被调节的目标用户范围内， - 该方法与 [setRemoteAudioPlaybackVolume](#RTCEngine-setremoteaudioplaybackvolume) 互斥，最新调用的任一方法设置的音量将覆盖此前已设置的音量，效果不叠加； - 当该方法与 [setPlaybackVolume](#RTCEngine-setplaybackvolume) 方法共同使用时，本地收听用户 A 的音量将为两次设置的音量效果的叠加。 ### setAudioSelectionConfig ```java public abstract int com.ss.bytertc.engine.RTCRoom.setAudioSelectionConfig(AudioSelectionPriority audioSelectionPriority) ``` > Available since 3.52 设置本端发布流在音频选路中的优先级。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audioSelectionPriority | AudioSelectionPriority | 本端发布流在音频选路中的优先级，默认正常参与音频选路。参见 [AudioSelectionPriority](70083#AudioSelectionPriority)。 | **注意** 在控制台上为本 appId 开启音频选路后，调用本接口才会生效。进房前后调用均可生效。更多信息参见[音频选路](https://www.volcengine.com/docs/6348/113547)。如果本端用户同时加入不同房间，使用本接口进行的设置相互独立。 ### setRoomExtraInfo ```java public abstract long com.ss.bytertc.engine.RTCRoom.setRoomExtraInfo( String key, String value ) ``` > Available since 3.52 设置/更新 RTC 房间附加信息，可用于标识房间状态或属性，或灵活实现各种业务逻辑。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | key | String | 房间附加信息键值，长度小于 10 字节。
同一房间内最多可存在 5 个 key，超出则会从第一个 key 起进行替换。 | | value | String | 房间附加信息内容，长度小于 128 字节。 | **返回值** - 0：方法调用成功，返回本次调用的任务编号； - < 0：方法调用失败，具体原因详见 [SetRoomExtraInfoResult](70083#SetRoomExtraInfoResult)。 **注意** - 在设置房间附加信息前，必须先调用 [joinRoom](#RTCRoom-joinroom) 加入房间。 - 调用该方法后，会收到一次 [onSetRoomExtraInfoResult](70081#IRTCRoomEventHandler-onsetroomextrainforesult) 回调，提示设置结果。 - 调用该方法成功设置附加信息后，同一房间内的其他用户会收到关于该信息的回调 [onRoomExtraInfoUpdate](70081#IRTCRoomEventHandler-onroomextrainfoupdate)。 - 新进房的用户会收到进房前房间内已有的全部附加信息通知。 ### setStreamExtraInfo ```java public abstract int com.ss.bytertc.engine.RTCRoom.setStreamExtraInfo(String extra_info) ``` 设置当前推流的流附加信息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | extra_info | String | 流附加信息。长度不超过1024的字符串。 | **返回值** 方法调用结果： + 0：成功。 + !0：失败。 **注意** + 可通过此函数设置当前推流的流附加信息。流附加信息是流 ID 的附加信息标识，不同于流 ID 在推流过程中不可修改，流附加信息可以在对应流 ID 的推流中途修改。开发者可根据流附加信息来实现流 ID 相关的可变内容的同步。 + 该方法在进房前后均可调用 + 相同房间内的其他用户会通过 [onRoomStreamExtraInfoUpdate] 回调函数获得通知。 ### setRemoteVideoConfig ```java public abstract int com.ss.bytertc.engine.RTCRoom.setRemoteVideoConfig( String streamId, RemoteVideoConfig remoteVideoConfig ) ``` 设置期望订阅的远端视频流的参数。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 期望配置订阅参数的远端视频流 ID。 | | remoteVideoConfig | RemoteVideoConfig | 期望配置的远端视频流参数，参看 [RemoteVideoConfig](70083#RemoteVideoConfig)。 | **返回值** 方法调用结果： + 0：成功。 + !0：失败。 **注意** + 若使用 342 及以前版本的 SDK，调用该方法前请联系技术支持人员开启按需订阅功能。 + 该方法仅在发布端调用 [setLocalSimulcastMode](#RTCEngine-setlocalsimulcastmode) 开启了发送多路视频流的情况下生效，此时订阅端将收到来自发布端与期望设置的参数最相近的一路流；否则订阅端只会收到一路参数为分辨率 640px × 360px、帧率 15fps 的视频流。 + 若发布端开启了推送多路流功能，但订阅端不对流参数进行设置，则默认接受发送端设置的分辨率最大的一路视频流。 + 该方法需在进房后调用。 + SDK 会根据发布端和所有订阅端的设置灵活调整视频流的参数，具体调整策略详见[推送多路流](https://www.volcengine.com/docs/6348/70139)文档。 ### startSubtitle ```java public abstract int com.ss.bytertc.engine.RTCRoom.startSubtitle(SubtitleConfig subtitleConfig) ``` > Available since 3.52 识别或翻译房间内所有用户的语音，形成字幕。调用该方法时，可以在 [SubtitleMode](70083#SubtitleMode) 中选择语音识别或翻译模式。如果选择识别模式，语音识别文本会通过 [onSubtitleMessageReceived](70081#IRTCRoomEventHandler-onsubtitlemessagereceived) 事件回调给你；如果选择翻译模式，你会同时收到两个 [onSubtitleMessageReceived](70081#IRTCRoomEventHandler-onsubtitlemessagereceived) 回调，分别包含字幕原文及字幕译文。调用该方法后，你会收到 [onSubtitleStateChanged](70081#IRTCRoomEventHandler-onsubtitlestatechanged) 回调，通知字幕是否开启。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | subtitleConfig | SubtitleConfig | 字幕配置信息。参看 [SubtitleConfig](70083#SubtitleConfig)。 | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 使用字幕功能前，你需要在 [RTC 控制台](https://console.volcengine.com/rtc/cloudRTC?tab=subtitle) 开启实时字幕功能。 - 如果你需要使用流式语音识别模式，你应在 [语音技术控制台](https://console.volcengine.com/speech/service/16) 创建流式语音识别应用。创建时，服务类型应选择 `流式语音识别`，而非 `音视频字幕生成`。创建后，在 [RTC 控制台](https://console.volcengine.com/rtc/cloudRTC?tab=subtitle) 上启动流式语音识别，并填写创建语音技术应用时获取的相关信息，包括：APP ID，Access Token，和 Cluster ID。 - 如果你需要使用实时语音翻译模式，你应开通机器翻译服务，参考 [开通服务](https://www.volcengine.com/docs/4640/130262)。完成开通后，在 [RTC 控制台](https://console.volcengine.com/rtc/cloudRTC?tab=subtitle) 上启用实时语音翻译模式。 - 此方法需要在进房后调用。 - 如需指定源语言，你需要在调用 `joinRoom` 接口进房时，通过 extraInfo 参数传入格式为`"语种英文名"："语种代号"` JSON 字符串，例如设置源语言为英文时，传入 `"source_language"："en"`。如未指定源语言，SDK 会将系统语种设定为源语言。如果你的系统语种不是中文、英文和日文，此时 SDK 会自动将中文设为源语言。 - 识别模式下，你可以传入 [RTC 控制台](https://console.volcengine.com/rtc/cloudRTC?tab=subtitle)上预设或自定义的语种英文名和语种代号。识别模式下支持的语言参看[识别模式语种支持](https://www.volcengine.com/docs/6561/109880#场景-语种支持)。 - 翻译模式下，你需要传入机器翻译规定的语种英文名和语种代号。翻译模式下支持的语言及对应的代号参看[翻译模式语言支持](https://www.volcengine.com/docs/4640/35107)。 ### stopSubtitle ```java public abstract int com.ss.bytertc.engine.RTCRoom.stopSubtitle() ``` > Available since 3.52 关闭字幕。调用该方法后，用户会收到 [onSubtitleStateChanged](70081#IRTCRoomEventHandler-onsubtitlestatechanged) 回调，通知字幕是否关闭。 **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### getRoomId ```java public abstract String com.ss.bytertc.engine.RTCRoom.getRoomId() ``` > Available since 3.53 获取 RTC 房间 ID。 **返回值** 房间 ID。 ### getCallId ```java public abstract String com.ss.bytertc.engine.RTCRoom.getCallId() ``` > Available since 3.60. 获取通话 ID。该方法需要在加入 RTC 房间后调用。当创建一个房间开启音视频通话后，系统会为该房间生成一个对应的通话 ID，标识此房间的通话。 **返回值** 通话 ID。 # IWTNStream ```java public interface com.ss.bytertc.engine.IWTNStream ``` WTN 流处理 ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract int | [subscribeWTNVideoStream](#IWTNStream-subscribewtnvideostream) | | abstract int | [subscribeWTNAudioStream](#IWTNStream-subscribewtnaudiostream) | | abstract int | [setWTNRemoteVideoCanvas](#IWTNStream-setwtnremotevideocanvas) | | abstract int | [setWTNRemoteVideoSink](#IWTNStream-setwtnremotevideosink) | | abstract int | [setWTNRemoteAudioPlaybackVolume](#IWTNStream-setwtnremoteaudioplaybackvolume) | | abstract int | [setWTNStreamEventHandler](#IWTNStream-setwtnstreameventhandler) | ## 函数说明 ### subscribeWTNVideoStream ```java abstract int com.ss.bytertc.engine.IWTNStream.subscribeWTNVideoStream( String streamId, boolean subscribe ) ``` > Available since 3.60. 自 3.60 起，此接口替代了 `startPlayPublicStream` 和 `stopPlayPublicStream` 方法来订阅/取消订阅指定 WTN 视频流，如果你使用了这两个方法，请迁移至此接口。订阅/取消订阅指定 WTN 视频流无论用户是否在房间内，都可以调用本接口订阅/取消订阅指定的 WTN 视频流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | WTN 流 ID，如果指定流暂未发布，则本地客户端将在其开始发布后接收到流数据。 | | subscribe | boolean | 是否订阅 WTN 流

true：订阅
false：取消订阅

| **返回值** - 0：成功。同时将收到 [onWTNVideoSubscribeStateChanged](70081#IWTNStreamEventHandler-onwtnvideosubscribestatechanged) 回调。 - !0：失败。当参数不合法或参数为空，调用失败。 **注意** - 一个客户端最多同时播放 5 路 WTN 流，请及时调用 [subscribeWTNVideoStream](#IWTNStream-subscribewtnvideostream)/[subscribeWTNAudioStream](#IWTNStream-subscribewtnaudiostream) 取消订阅 WTN 流，避免订阅的 WTN 流数量超限。 - 在调用本接口之前，建议先绑定渲染视图。 - 调用 [setWTNRemoteVideoCanvas](#IWTNStream-setwtnremotevideocanvas) 绑定内部渲染视图 - 调用 [setWTNRemoteVideoSink](#IWTNStream-setwtnremotevideosink) 绑定自定义渲染视图 - 调用本接口后，可以通过 [onWTNFirstRemoteVideoFrameDecoded](70081#IWTNStreamEventHandler-onwtnfirstremotevideoframedecoded) 回调 WTN 视频流的首帧解码情况。 - 调用本接口后，可以通过 [onWTNSEIMessageReceived](70081#IWTNStreamEventHandler-onwtnseimessagereceived) 回调 WTN 流中包含的 SEI 信息。 ### subscribeWTNAudioStream ```java abstract int com.ss.bytertc.engine.IWTNStream.subscribeWTNAudioStream( String streamId, boolean subscribe ) ``` > Available since 3.60. 自 3.60 起，此接口替代了 `startPlayPublicStream` 和 `stopPlayPublicStream` 方法来订阅/取消订阅指定 WTN 音频流，如果你使用了这两个方法，请迁移至此接口。订阅/取消订阅指定 WTN 音频流无论用户是否在房间内，都可以调用本接口订阅/取消订阅指定的 WTN 音频流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | WTN 流 ID，如果指定流暂未发布，则本地客户端将在其开始发布后接收到流数据。 | | subscribe | boolean | 是否订阅 WTN 流

true：订阅
false：取消订阅

| **返回值** - 0：成功。同时将收到 [onWTNAudioSubscribeStateChanged](70081#IWTNStreamEventHandler-onwtnaudiosubscribestatechanged) 回调。 - !0：失败。当参数不合法或参数为空，调用失败。 **注意** - 一个客户端最多同时播放 5 路 WTN 流，请及时调用 [subscribeWTNVideoStream](#IWTNStream-subscribewtnvideostream)/[subscribeWTNAudioStream](#IWTNStream-subscribewtnaudiostream) 取消订阅WTN 流，避免订阅的 WTN 流数量超限。 - 在调用本接口之前，建议先绑定渲染视图。 - 调用 [setWTNRemoteVideoCanvas](#IWTNStream-setwtnremotevideocanvas) 绑定内部渲染视图 - 调用 [setWTNRemoteVideoSink](#IWTNStream-setwtnremotevideosink) 绑定自定义渲染视图 - 调用本接口后，可以通过 [onWTNFirstRemoteAudioFrame](70081#IWTNStreamEventHandler-onwtnfirstremoteaudioframe) 回调 WTN 音频流的音频首帧解码情况。 - 调用本接口后，可以通过 [onWTNSEIMessageReceived](70081#IWTNStreamEventHandler-onwtnseimessagereceived) 回调 WTN 流中包含的 SEI 信息。 ### setWTNRemoteVideoCanvas ```java abstract int com.ss.bytertc.engine.IWTNStream.setWTNRemoteVideoCanvas( String streamId, VideoCanvas canvas ) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `setPublicStreamVideoCanvas` 方法来实现下述功能。你已升级至 3.60 及以上版本，并且仍在使用该方法，请迁移到此接口。为指定 WTN 流绑定内部渲染视图 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | WTN 流 ID | | canvas | VideoCanvas | 内部渲染视图，如果需要解除视频的绑定视图，把 [VideoCanvas](70083#VideoCanvas) 设置为空。 | **返回值** - 0：成功 - !0：失败 ### setWTNRemoteVideoSink ```java abstract int com.ss.bytertc.engine.IWTNStream.setWTNRemoteVideoSink( String streamId, IVideoSink videoSink, RemoteVideoSinkConfig config ) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `setPublicStreamVideoSink` 方法来实现下述功能。你已升级至 3.60 及以上版本，并且仍在使用该方法，请迁移到此接口。为指定 WTN 流绑定自定义渲染器。详见[自定义视频渲染](https://www.volcengine.com/docs/6348/81201)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | WTN 流 ID | | videoSink | IVideoSink | 自定义视频渲染器，自定义视频渲染器，需要释放渲染器资源时，将 `videoSink` 设置为 `null`。参看 [IVideoSink](70083#IVideoSink) | | config | RemoteVideoSinkConfig | 远端视频帧回调配置，参看 [RemoteVideoSinkConfig](70083#RemoteVideoSinkConfig) | **返回值** - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 ### setWTNRemoteAudioPlaybackVolume ```java abstract int com.ss.bytertc.engine.IWTNStream.setWTNRemoteAudioPlaybackVolume( String streamId, int volume ) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `setPublicStreamAudioPlaybackVolume` 方法来实现下述功能。你已升级至 3.60 及以上版本，并且仍在使用该方法，请迁移到此接口。调节 WTN 流的音频播放音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | WTN 流 ID | | volume | int | 音频播放音量值和原始音量值的比值，该比值的范围是 `[0, 400]`，单位为 \%，且自带溢出保护。为保证更好的音频质量，建议设定在 `[0, 100]` 之间，其中 100 为系统默认值。 | **返回值** - 0：成功调用。 - -2：参数错误。 ### setWTNStreamEventHandler ```java abstract int com.ss.bytertc.engine.IWTNStream.setWTNStreamEventHandler(IWTNStreamEventHandler handler) ``` > Available since 3.60. 设置 WTN 流回调接口 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | handler | IWTNStreamEventHandler | WTN 回调类，参看 [IWTNStreamEventHandler](70081#IWTNStreamEventHandler)。 | # IVideoProcessor ```java public abstract class com.ss.bytertc.engine.video.IVideoProcessor ``` 视频处理 ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract IVideoFrame | [processVideoFrame](#IVideoProcessor-processvideoframe) | ## 函数说明 ### processVideoFrame ```java public abstract IVideoFrame com.ss.bytertc.engine.video.IVideoProcessor.processVideoFrame(IVideoFrame frame) ``` 获取 RTC SDK 采集得到的视频帧，根据 [registerLocalVideoProcessor](#RTCEngine-registerlocalvideoprocessor) 设置的视频前处理器，进行视频前处理，最终将处理后的视频帧给到 RTC SDK 用于编码传输。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | frame | IVideoFrame | RTC SDK 采集得到的视频帧，参看 [IVideoFrame](70083#IVideoFrame)。 | **返回值** 经过视频前处理后的视频帧，返回给 RTC SDK 供编码和传输，参看 [IVideoFrame](70083#IVideoFrame)。 **注意** - 在进行视频前处理前，你需要调用 [registerLocalVideoProcessor](#RTCEngine-registerlocalvideoprocessor) 设置视频前处理器。 - 如果需要取消视频前处理，可以将视频前处理器设置为 nullptr。 - 对于纹理类型的视频数据，应用层需要在自己的工作线程准备OpenGL上下文进行视频处理。 - 应用层实现IVideoProcessor.processVideoFrame 接口时，可以直接修改参数 frame 的缓冲区，将frame引用计数加一(调用addRef方法)，然后将修改后的frame返回。应用层也可以创建一个新的视频帧并返回。 - 对于 IVideoProcessor.processVideoFrame返回的视频帧，在SDK层消费完成后，SDK内部总是调用这个视频帧的releaseRef方法。 # IGameRoom ```java public abstract class com.ss.bytertc.engine.IGameRoom ``` IGameRoom 类，提供游戏房间相关接口。 ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract void | [destroy](#IGameRoom-destroy) | | abstract int | [joinRoom](#IGameRoom-joinroom) | | abstract int | [setRTCRoomEventHandler](#IGameRoom-setrtcroomeventhandler) | | abstract int | [leaveRoom](#IGameRoom-leaveroom) | | abstract int | [updateToken](#IGameRoom-updatetoken) | | abstract IRangeAudio | [getRangeAudio](#IGameRoom-getrangeaudio) | | abstract int | [enableMicrophone](#IGameRoom-enablemicrophone) | | abstract int | [enableSpeakerphone](#IGameRoom-enablespeakerphone) | | abstract int | [enableAudioSend](#IGameRoom-enableaudiosend) | | abstract int | [enableAudioReceive](#IGameRoom-enableaudioreceive) | | abstract int | [setRemoteRoomAudioPlaybackVolume](#IGameRoom-setremoteroomaudioplaybackvolume) | ## 函数说明 ### destroy ```java public abstract void com.ss.bytertc.engine.IGameRoom.destroy() ``` 退出并销毁调用 [createGameRoom](#RTCEngine-creategameroom) 所创建的游戏房间实例。 ### joinRoom ```java public abstract int com.ss.bytertc.engine.IGameRoom.joinRoom( String token, UserInfo userInfo ) ``` 加入游戏房间。调用 [createGameRoom](#RTCEngine-creategameroom) 创建游戏房间实例后，调用此方法加入游戏房间，同房间内其他用户进行音频通话。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | String | 动态密钥。用于对进房用户进行鉴权验证。
进入房间需要携带 Token。测试时可使用控制台生成临时 Token，正式上线需要使用密钥 SDK 在你的服务端生成并下发 Token。Token 有效期及生成方式参看[使用 Token 完成鉴权](70121)。
使用不同 AppID 的 App 是不能互通的。
请务必保证生成 Token 使用的 AppID 和创建引擎时使用的 AppID 相同，否则会导致加入房间失败。 | | userInfo | UserInfo | 用户信息。参看 [UserInfo](70083#UserInfo)。 | **返回值** - 0：方法调用成功。触发以下回调： - 本端收到房间状态通知 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged) 回调。 - 本端收到房间内已发布流的通知 [onUserPublishStreamAudio](70081#IRTCRoomEventHandler-onuserpublishstreamaudio) 回调。 - -1：roomID / userInfo.uid 包含了无效的参数。 - -2：已经在房间内。接口调用成功后，只要收到返回值为 0 ，且未调用 [leaveRoom](#IGameRoom-leaveroom) 成功，则再次调用进房接口时，无论填写的房间 ID 和用户 ID 是否重复，均触发此返回值。调用失败时，具体失败原因会通过 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged) 回调告知。 **注意** - 该接口必须在调用 [setAudioScenario](70080#RTCEngine-setaudioscenario) 之后调用。 - 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后进房的用户会将先进房的用户踢出房间，并且先进房的用户会收到 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged) 回调通知，错误类型详见 [ERROR_CODE_DUPLICATE_LOGIN](70082#ErrorCode-error_code_duplicate_login)。 - 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，并触发 [onConnectionStateChanged](70081#IRTCEngineEventHandler-onconnectionstatechanged) 回调。此时 SDK 会自动重试，直到成功重连。重连成功后，本地会收到 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged) 回调通知；如果加入房间的用户是可见用户，远端用户会收到 [onUserJoined](70081#IRTCRoomEventHandler-onuserjoined) 回调通知。 ### setRTCRoomEventHandler ```java public abstract int com.ss.bytertc.engine.IGameRoom.setRTCRoomEventHandler(IRTCRoomEventHandler rtcRoomEventHandler) ``` 通过设置 [IGameRoom](#IGameRoom) 对象的事件句柄，监听此对象对应的回调事件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | rtcRoomEventHandler | IRTCRoomEventHandler | 参看 [IRTCRoomEventHandler](70081#IRTCRoomEventHandler) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### leaveRoom ```java public abstract int com.ss.bytertc.engine.IGameRoom.leaveRoom() ``` 离开游戏房间。调用此方法结束通话过程，并释放所有通话相关的资源。 **返回值** - 0：调用成功。如果用户是房间内可见用户，触发以下回调： - 远端用户收到 [onUserLeave](70081#IRTCRoomEventHandler-onuserleave) 回调通知。 - 正在发布的流会被取消发布。远端用户收到 [onAudioPublishStateChanged](70081#IRTCRoomEventHandler-onaudiopublishstatechanged) 回调通知。 - < 0：调用失败，参看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 加入游戏房间后，必须调用此方法结束通话，否则无法开始下一次通话。 - 此方法是异步操作，调用返回时并没有真正退出房间。真正退出房间后，本地会收到 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged) 回调通知。你必须在收到 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged) 回调后，再销毁房间或引擎，或调用 [joinRoom](#RTCRoom-joinroom) 再次加入房间。 - 调用 [setUserVisibility](#RTCRoom-setuservisibility) 将自身设为可见的用户离开房间后，房间内其他用户会收到 [onUserLeave](70081#IRTCRoomEventHandler-onuserleave) 回调通知。 ### updateToken ```java public abstract int com.ss.bytertc.engine.IGameRoom.updateToken(String token) ``` 更新游戏房间的 Token。收到 [onTokenWillExpire](70081#IRTCRoomEventHandler-ontokenwillexpire)，[onPublishPrivilegeTokenWillExpire](70081#IRTCRoomEventHandler-onpublishprivilegetokenwillexpire)，或 [onSubscribePrivilegeTokenWillExpire](70081#IRTCRoomEventHandler-onsubscribeprivilegetokenwillexpire) 时，你必须重新获取 Token，并调用此方法更新 Token，以保证通话的正常进行。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | String | 重新获取的有效 Token。
如果 Token 无效，你会收到 [onRoomStateChanged](70081#IRTCRoomEventHandler-onroomstatechanged)，错误码是 `-1010`。 | **返回值** 方法调用结果： - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** 请勿同时调用 [updateToken](#IGameRoom-updatetoken) 和 [joinRoom](#IGameRoom-joinroom) 方法更新 Token。若因 Token 过期或无效导致加入房间失败或已被移出房间，你应该在获取新的有效 Token 后调用 [joinRoom](#IGameRoom-joinroom) 重新加入房间。 ### getRangeAudio ```java public abstract IRangeAudio com.ss.bytertc.engine.IGameRoom.getRangeAudio() ``` 获取游戏房间的范围语音接口实例。 **返回值** 方法调用结果： - IRangeAudio：成功，返回一个 [IRangeAudio](#IRangeAudio) 实例。 - null：失败，当前 SDK 不支持范围语音功能。 **注意** 首次调用该方法须在创建房间后、加入房间前。范围语音相关 API 和调用时序详见[范围语音](https://www.volcengine.com/docs/6348/114727)。 ### enableMicrophone ```java public abstract int com.ss.bytertc.engine.IGameRoom.enableMicrophone(boolean enable) ``` 加入游戏房间后，调用该接口开启或关闭麦克风。同房间其他用户会收到回调 [OnAudioDeviceStateChanged](70081#IRTCEngineEventHandler-onaudiodevicestatechanged)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 是否开启麦克风：

true：开启麦克风，采集并发布音频流。
false：默认设置。关闭麦克风并停止发布音频流。

| **返回值** - 0：接口调用成功。 - -3：接口调用失败。没有加入房间。 **注意** 不可与 [enableAudioSend](#IGameRoom-enableaudiosend) 同时调用。 ### enableSpeakerphone ```java public abstract int com.ss.bytertc.engine.IGameRoom.enableSpeakerphone(boolean enable) ``` 加入游戏房间后，开启或关闭扬声器。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 是否开启扬声器：

true：开启扬声器，接收所有远端用户的音频流。
false：默认设置。关闭扬声器，停止接收所有远端用户的音频流。

| **返回值** - 0：接口调用成功。 - -3：接口调用失败。没有加入房间。 ### enableAudioSend ```java public abstract int com.ss.bytertc.engine.IGameRoom.enableAudioSend(boolean enable) ``` 加入游戏房间后，开始或停止发送音频流。调用此接口不影响音频采集。同房间其他用户会收到相应的回调。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 是否发送音频流：

true：发送音频流。
false：默认设置。停止发送音频流（不会关闭麦克风），即静音。

| **返回值** - 0：表示参数检查通过，不代表打开麦克风会成功，比如房间不存在 - -3：接口调用失败。没有加入房间。 **注意** 不可与 [EnableMicrophone](#IGameRoom-enablemicrophone) 同时调用。 ### enableAudioReceive ```java public abstract int com.ss.bytertc.engine.IGameRoom.enableAudioReceive( String userId, boolean enable ) ``` 是否接收某个特定用户的音频流。关闭声音接收不会影响扬声器或其他音频输出设备的状态。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | userId | String | 用户 ID，最大长度为128字节的非空字符串。支持的字符集范围为：

26个大写字母 A ~ Z
26个小写字母 a ~ z
10个数字 0 ~ 9
下划线"_", at符"\@", 减号"-"

| | enable | boolean | 是否接收指定用户的音频流：

true：接收该用户的音频流。即允许该用户的音频数据被传递到本地设备并播放。
false：默认设置，不接收该用户的音频流，即不播放该用户的声音。但不会关闭扬声器，扬声器仍可用于其他音频输出。

| **返回值** - 0：接口调用成功 - -2：传入的用户 ID 为空字符串。 ### setRemoteRoomAudioPlaybackVolume ```java public abstract int com.ss.bytertc.engine.IGameRoom.setRemoteRoomAudioPlaybackVolume(int volume) ``` 调节某个游戏房间内所有远端用户的音频播放音量（非系统硬件音量）。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 音频播放音量值和原始音量的比值，范围是 [0, 400]，单位为 \%，自带溢出保护。为保证更好的通话质量，建议将 volume 值设为 [0,100]。

0：静音
100：原始音量，默认值
400：最大可为原始音量的 4 倍(自带溢出保护)

| **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 假设某远端用户 A 始终在被调节的目标用户范围内， - 该方法与 [setRemoteAudioPlaybackVolume](#RTCEngine-setremoteaudioplaybackvolume) 互斥，最新调用的任一方法设置的音量将覆盖此前已设置的音量，效果不叠加； - 当该方法与 [setPlaybackVolume](#RTCEngine-setplaybackvolume) 方法共同使用时，本地收听用户 A 的音量将为两次设置的音量效果的叠加。 # RTSRoom ```java public abstract class com.ss.bytertc.engine.RTSRoom ``` RTSRoom Class ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract void | [destroy](#RTSRoom-destroy) | | abstract int | [joinRTSRoom](#RTSRoom-joinrtsroom) | | abstract int | [updateToken](#RTSRoom-updatetoken) | | abstract int | [leaveRoom](#RTSRoom-leaveroom) | | abstract int | [setRTSRoomEventHandler](#RTSRoom-setrtsroomeventhandler) | | abstract long | [sendUserMessage](#RTSRoom-sendusermessage) | | abstract long | [sendUserBinaryMessage](#RTSRoom-senduserbinarymessage) | | abstract long | [sendRoomMessage](#RTSRoom-sendroommessage) | | abstract long | [sendRoomBinaryMessage](#RTSRoom-sendroombinarymessage) | ## 函数说明 ### destroy ```java public abstract void com.ss.bytertc.engine.RTSRoom.destroy() ``` 退出并销毁调用 [createRTSRoom](#RTCEngine-creatertsroom) 所创建的房间实例。 ### joinRTSRoom ```java public abstract int com.ss.bytertc.engine.RTSRoom.joinRTSRoom( String token, UserInfo userInfo ) ``` 加入 RTS 房间。调用 [createRTSRoom](#RTCEngine-creatertsroom) 创建房间后，调用此方法加入房间，同房间内其他用户进行音视频通话。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | String | 动态密钥。用于对进房用户进行鉴权验证。
进入房间需要携带 Token。测试时可使用控制台生成临时 Token，正式上线需要使用密钥 SDK 在你的服务端生成并下发 Token。Token 有效期及生成方式参看[使用 Token 完成鉴权](70121)。
使用不同 AppID 的 App 是不能互通的。
请务必保证生成 Token 使用的 AppID 和创建引擎时使用的 AppID 相同，否则会导致加入房间失败。 | | userInfo | UserInfo | 用户信息。参看 [UserInfo](70083#UserInfo)。 | **返回值** - 0：方法调用成功。 - 0：成功。触发以下回调： - 本端收到房间状态通知 [onRoomStateChanged](70081#IRTSRoomEventHandler-onroomstatechanged) 回调。 - -1：roomID / userInfo.uid 包含了无效的参数。 - -2：已经在房间内。接口调用成功后，只要收到返回值为 0 ，且未调用 [leaveRoom](#RTSRoom-leaveroom) 成功，则再次调用进房接口时，无论填写的房间 ID 和用户 ID 是否重复，均触发此返回值。调用失败时，具体失败原因会通过 [onRoomStateChanged](70081#IRTSRoomEventHandler-onroomstatechanged) 回调告知。 **注意** - 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后进房的用户会将先进房的用户踢出房间，并且先进房的用户会收到 [onRoomStateChanged](70081#IRTSRoomEventHandler-onroomstatechanged) 回调通知，错误类型详见 [ERROR_CODE_DUPLICATE_LOGIN](70082#ErrorCode-error_code_duplicate_login)。 - 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，并触发 [onConnectionStateChanged](70081#IRTCEngineEventHandler-onconnectionstatechanged) 回调。此时 SDK 会自动重试，直到成功重连。重连成功后，本地会收到 [onRoomStateChanged](70081#IRTSRoomEventHandler-onroomstatechanged) 回调通知；如果加入房间的用户是可见用户，远端用户会收到 [onUserJoined](70081#IRTSRoomEventHandler-onuserjoined) 回调通知。 ### updateToken ```java public abstract int com.ss.bytertc.engine.RTSRoom.updateToken(String token) ``` 更新房间的 Token。收到 [onTokenWillExpire](70081#IRTCRoomEventHandler-ontokenwillexpire)，[onPublishPrivilegeTokenWillExpire](70081#IRTCRoomEventHandler-onpublishprivilegetokenwillexpire)，或 [onSubscribePrivilegeTokenWillExpire](70081#IRTCRoomEventHandler-onsubscribeprivilegetokenwillexpire) 时，你必须重新获取 Token，并调用此方法更新 Token，以保证通话的正常进行。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | String | 重新获取的有效 Token。
如果 Token 无效，你会收到 [onRoomStateChanged](70081#IRTSRoomEventHandler-onroomstatechanged)，错误码是 `-1010`。 | **返回值** 方法调用结果： - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** - 请勿同时调用 [updateToken](#RTSRoom-updatetoken) 和 [joinRTSRoom](#RTSRoom-joinrtsroom) 方法更新 Token。若因 Token 过期或无效导致加入房间失败或已被移出房间，你应该在获取新的有效 Token 后调用 [joinRTSRoom](#RTSRoom-joinrtsroom) 重新加入房间。 ### leaveRoom ```java public abstract int com.ss.bytertc.engine.RTSRoom.leaveRoom() ``` 离开 RTS 房间。调用此方法结束通话过程，并释放所有通话相关的资源。 **返回值** - 0：调用成功。如果用户是房间内可见用户，触发以下回调： - 远端用户收到 [onUserLeave](70081#IRTSRoomEventHandler-onuserleave) 回调通知。 - < 0：调用失败，参看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 加入房间后，必须调用此方法结束通话，否则无法开始下一次通话。 - 此方法是异步操作，调用返回时并没有真正退出房间。真正退出房间后，本地会收到 [onRoomStateChanged](70081#IRTSRoomEventHandler-onroomstatechanged) 回调通知。你必须在收到 [onRoomStateChanged](70081#IRTSRoomEventHandler-onroomstatechanged) 回调后，再销毁房间或引擎，或调用 [joinRTSRoom](#RTSRoom-joinrtsroom) 再次加入房间。 - 调用 [setUserVisibility](#RTCRoom-setuservisibility) 将自身设为可见的用户离开房间后，房间内其他用户会收到 [onUserLeave](70081#IRTSRoomEventHandler-onuserleave) 回调通知。 ### setRTSRoomEventHandler ```java public abstract int com.ss.bytertc.engine.RTSRoom.setRTSRoomEventHandler(IRTSRoomEventHandler rtcRoomEventHandler) ``` 通过设置 [RTSRoom](#RTSRoom) 对象的事件句柄，监听此对象对应的回调事件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | rtcRoomEventHandler | IRTSRoomEventHandler | 参看 [IRTSRoomEventHandler](70081#IRTSRoomEventHandler) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### sendUserMessage ```java public abstract long com.ss.bytertc.engine.RTSRoom.sendUserMessage( String userId, String messageStr, MessageConfig config ) ``` 给房间内指定的用户发送点对点文本消息（P2P）。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | userId | String | 消息接收用户的 ID | | messageStr | String | 发送的文本消息内容。消息不超过 64 KB。 | | config | MessageConfig | 消息发送的可靠/有序类型，参看 [MessageConfig](70083#MessageConfig) | **返回值** - \>0：发送成功，返回这次发送消息的编号，从 1 开始递增 - -1：发送失败，RTCRoom 实例未创建 - -2：发送失败，uid 为空 **注意** - 在发送房间内文本消息前，必须先调用 [joinRTSRoom](#RTSRoom-joinrtsroom) 加入房间。 - 调用后，会收到 [onUserMessageSendResult](70081#IRTSRoomEventHandler-onusermessagesendresult) 回调，通知消息发送成功或失败； - 若消息发送成功，则 userId 所指定的用户会收到 [onUserMessageReceived](70081#IRTSRoomEventHandler-onusermessagereceived) 回调。 ### sendUserBinaryMessage ```java public abstract long com.ss.bytertc.engine.RTSRoom.sendUserBinaryMessage( String userId, byte[] buffer, MessageConfig config ) ``` 给房间内指定的用户发送点对点二进制消息（P2P）。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | userId | String | 消息接收用户的 ID | | buffer | byte[] | 发送的二进制消息内容。消息不超过 64KB。 | | config | MessageConfig | 消息发送的可靠/有序类型，参看 [MessageConfig](70083#MessageConfig)。 | **注意** - 在发送房间内二进制消息前，必须先调用 [joinRTSRoom](#RTSRoom-joinrtsroom) 加入房间。 - 调用后，会收到 [onUserMessageSendResult](70081#IRTSRoomEventHandler-onusermessagesendresult) 回调，通知消息发送成功或失败； - 若消息发送成功，则 userId 所指定的用户会收到 [onUserBinaryMessageReceived](70081#IRTSRoomEventHandler-onuserbinarymessagereceived) 回调。 ### sendRoomMessage ```java public abstract long com.ss.bytertc.engine.RTSRoom.sendRoomMessage(String messageStr) ``` 给房间内的所有其他用户群发文本消息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | messageStr | String | 发送的文本消息内容，消息不超过 64 KB。 | **注意** - 在房间内广播文本消息前，必须先调用 [joinRTSRoom](#RTSRoom-joinrtsroom) 加入房间。 - 调用后，会收到 [onRoomMessageSendResult](70081#IRTSRoomEventHandler-onroommessagesendresult) 回调； - 同一房间内的其他用户会收到 [onRoomMessageReceived](70081#IRTSRoomEventHandler-onroommessagereceived) 回调。 ### sendRoomBinaryMessage ```java public abstract long com.ss.bytertc.engine.RTSRoom.sendRoomBinaryMessage(byte[] buffer) ``` 给房间内的所有其他用户群发二进制消息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | buffer | byte[] | 发送的二进制消息内容，消息不超过 64KB。 | **注意** - 在房间内广播二进制消息前，必须先调用 [joinRTSRoom](#RTSRoom-joinrtsroom) 加入房间。 - 调用后，会收到 [onRoomMessageSendResult](70081#IRTSRoomEventHandler-onroommessagesendresult) 回调； - 同一房间内的其他用户会收到 [onRoomBinaryMessageReceived](70081#IRTSRoomEventHandler-onroombinarymessagereceived) 回调。 # IRangeAudio ```java public interface com.ss.bytertc.engine.audio.IRangeAudio ``` 范围语音接口实例 ## 成员函数 | 返回 | 名称 | | --- | --- | | void | [enableRangeAudio](#IRangeAudio-enablerangeaudio) | | int | [updatePosition](#IRangeAudio-updateposition) | | int | [updateReceiveRange](#IRangeAudio-updatereceiverange) | | int | [setAttenuationModel](#IRangeAudio-setattenuationmodel) | | void | [setNoAttenuationFlags](#IRangeAudio-setnoattenuationflags) | ## 函数说明 ### enableRangeAudio ```java void com.ss.bytertc.engine.audio.IRangeAudio.enableRangeAudio(boolean enable) ``` 开启/关闭范围语音功能。范围语音是指，在同一 RTC 房间中设定的音频接收距离范围内，本地用户收听到的远端用户音频音量会随着远端用户的靠近/远离而放大/衰减；若远端用户在房间内的位置超出设定范围，则本地用户无法接收其音频。音频接收范围设置参看 [updateReceiveRange](#IRangeAudio-updatereceiverange)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 是否开启范围语音功能：

true：开启
false：关闭（默认）

| **注意** 该方法进房前后都可调用，为保证进房后范围语音效果的平滑切换，你需在该方法前先调用 [updatePosition](#IRangeAudio-updateposition) 设置自身位置坐标，然后开启该方法收听范围语音效果。 ### updatePosition ```java int com.ss.bytertc.engine.audio.IRangeAudio.updatePosition(Position pos) ``` 更新本地用户在房间内空间直角坐标系中的位置坐标。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | pos | Position | 三维坐标的值，默认为 [0, 0, 0]，参看 [Position](70083#Position) | **返回值** 方法调用结果： - 0：成功。 - !0：失败。 **注意** - 调用该接口更新坐标后，你需调用 [enableRangeAudio](#IRangeAudio-enablerangeaudio) 开启范围语音功能以收听范围语音效果。 ### updateReceiveRange ```java int com.ss.bytertc.engine.audio.IRangeAudio.updateReceiveRange(ReceiveRange range) ``` 更新本地用户的音频收听范围。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | range | ReceiveRange | 音频收听范围，参看 [ReceiveRange](70083#ReceiveRange)。 | **返回值** 方法调用结果： - 0：成功。 - !0：失败。 ### setAttenuationModel ```java int com.ss.bytertc.engine.audio.IRangeAudio.setAttenuationModel( AttenuationType type, float coefficient ) ``` 设置范围语音的音量衰减模式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | AttenuationType | 音量衰减模式。默认为线性衰减。详见 [AttenuationType](70083#AttenuationType)。 | | coefficient | float | 指数衰减模式下的音量衰减系数，默认值为 1。范围 [0.1,100]，推荐设置为 `50`。数值越大，音量的衰减速度越快。 | **返回值** 调用是否成功 - `0`:调用成功 - `-1`:调用失败。原因为在调用 [enableRangeAudio](#IRangeAudio-enablerangeaudio) 开启范围语音前或进房前调用本接口 **注意** 音量衰减范围通过 [updateReceiveRange](#IRangeAudio-updatereceiverange) 进行设置。 ### setNoAttenuationFlags ```java void com.ss.bytertc.engine.audio.IRangeAudio.setNoAttenuationFlags(List flags) ``` 添加标签组，用于标记相互之间通话不衰减的用户组。在同一个 RTC 房间中，如果多个用户的标签组之间有交集，那么，他们之间互相通话时，通话不衰减。比如，用户身处多个队伍，队伍成员间通话不衰减。那么，可以为每个队伍绑定专属标签，每个用户的标签组包含用户所属各个队伍的标签。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | flags | List\ | 标签组 | # RTCEngine ```java public abstract class com.ss.bytertc.engine.RTCEngine ``` RTCEngine Class ## 静态函数 | 返回 | 名称 | | --- | --- | | static synchronized RTCEngine | [createRTCEngine](#RTCEngine-creatertcengine) | | static synchronized void | [destroyRTCEngine](#RTCEngine-destroyrtcengine) | | static String | [getSDKVersion](#RTCEngine-getsdkversion) | | static int | [setLogConfig](#RTCEngine-setlogconfig) | ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract IRTCAudioDeviceManager | [getAudioDeviceManager](#RTCEngine-getaudiodevicemanager) | | abstract int | [startVideoCapture](#RTCEngine-startvideocapture) | | abstract int | [stopVideoCapture](#RTCEngine-stopvideocapture) | | abstract int | [startAudioCapture](#RTCEngine-startaudiocapture) | | abstract int | [stopAudioCapture](#RTCEngine-stopaudiocapture) | | abstract int | [setAudioScenario](#RTCEngine-setaudioscenario) | | abstract int | [setAudioProfile](#RTCEngine-setaudioprofile) | | abstract int | [setAnsMode](#RTCEngine-setansmode) | | abstract int | [setVoiceChangerType](#RTCEngine-setvoicechangertype) | | abstract int | [setVoiceReverbType](#RTCEngine-setvoicereverbtype) | | abstract int | [setLocalVoiceEqualization](#RTCEngine-setlocalvoiceequalization) | | abstract int | [setLocalVoiceReverbParam](#RTCEngine-setlocalvoicereverbparam) | | abstract int | [enableLocalVoiceReverb](#RTCEngine-enablelocalvoicereverb) | | abstract int | [setLocalVideoCanvas](#RTCEngine-setlocalvideocanvas) | | abstract int | [updateLocalVideoCanvas](#RTCEngine-updatelocalvideocanvas) | | abstract int | [setLocalVideoSink](#RTCEngine-setlocalvideosink-2) | | abstract int | [setLocalVideoMirrorType](#RTCEngine-setlocalvideomirrortype) | | abstract int | [setRemoteVideoMirrorType](#RTCEngine-setremotevideomirrortype) | | abstract int | [setVideoRotationMode](#RTCEngine-setvideorotationmode) | | abstract int | [switchCamera](#RTCEngine-switchcamera) | | abstract int | [setAudioRoute](#RTCEngine-setaudioroute) | | abstract AudioRoute | [getAudioRoute](#RTCEngine-getaudioroute) | | abstract int | [setDefaultAudioRoute](#RTCEngine-setdefaultaudioroute) | | abstract int | [enableExternalSoundCard](#RTCEngine-enableexternalsoundcard) | | abstract int | [muteAudioCapture](#RTCEngine-muteaudiocapture) | | abstract int | [muteScreenAudioCapture](#RTCEngine-mutescreenaudiocapture) | | abstract int | [setCaptureVolume](#RTCEngine-setcapturevolume) | | abstract int | [setScreenCaptureVolume](#RTCEngine-setscreencapturevolume) | | abstract int | [setPlaybackVolume](#RTCEngine-setplaybackvolume) | | abstract int | [setLocalVoicePitch](#RTCEngine-setlocalvoicepitch) | | abstract int | [enableVocalInstrumentBalance](#RTCEngine-enablevocalinstrumentbalance) | | abstract int | [enablePlaybackDucking](#RTCEngine-enableplaybackducking) | | abstract int | [login](#RTCEngine-login) | | abstract int | [logout](#RTCEngine-logout) | | abstract int | [updateLoginToken](#RTCEngine-updatelogintoken) | | abstract int | [setServerParams](#RTCEngine-setserverparams) | | abstract int | [getPeerOnlineStatus](#RTCEngine-getpeeronlinestatus) | | abstract long | [sendUserMessageOutsideRoom](#RTCEngine-sendusermessageoutsideroom) | | abstract long | [sendUserBinaryMessageOutsideRoom](#RTCEngine-senduserbinarymessageoutsideroom) | | abstract long | [sendServerMessage](#RTCEngine-sendservermessage) | | abstract long | [sendServerBinaryMessage](#RTCEngine-sendserverbinarymessage) | | abstract int | [startNetworkDetection](#RTCEngine-startnetworkdetection) | | abstract int | [stopNetworkDetection](#RTCEngine-stopnetworkdetection) | | abstract int | [enableAudioFrameCallback](#RTCEngine-enableaudioframecallback) | | abstract int | [disableAudioFrameCallback](#RTCEngine-disableaudioframecallback) | | abstract int | [registerAudioFrameObserver](#RTCEngine-registeraudioframeobserver) | | abstract int | [registerAudioProcessor](#RTCEngine-registeraudioprocessor) | | abstract int | [enableAudioProcessor](#RTCEngine-enableaudioprocessor) | | abstract int | [disableAudioProcessor](#RTCEngine-disableaudioprocessor) | | abstract int | [registerLocalVideoProcessor](#RTCEngine-registerlocalvideoprocessor) | | abstract int | [setVideoDigitalZoomConfig](#RTCEngine-setvideodigitalzoomconfig) | | abstract int | [setVideoDigitalZoomControl](#RTCEngine-setvideodigitalzoomcontrol) | | abstract int | [startVideoDigitalZoomControl](#RTCEngine-startvideodigitalzoomcontrol) | | abstract int | [stopVideoDigitalZoomControl](#RTCEngine-stopvideodigitalzoomcontrol) | | abstract int | [registerLocalEncodedVideoFrameObserver](#RTCEngine-registerlocalencodedvideoframeobserver) | | abstract int | [registerRemoteEncodedVideoFrameObserver](#RTCEngine-registerremoteencodedvideoframeobserver) | | abstract int | [setVideoSourceType](#RTCEngine-setvideosourcetype) | | abstract int | [pushExternalVideoFrame](#RTCEngine-pushexternalvideoframe) | | abstract int | [startPushMixedStream](#RTCEngine-startpushmixedstream) | | abstract int | [updatePushMixedStream](#RTCEngine-updatepushmixedstream) | | abstract int | [stopPushMixedStream](#RTCEngine-stoppushmixedstream) | | abstract int | [startPushSingleStream](#RTCEngine-startpushsinglestream) | | abstract int | [stopPushSingleStream](#RTCEngine-stoppushsinglestream) | | abstract int | [setVideoCaptureConfig](#RTCEngine-setvideocaptureconfig) | | abstract int | [setVideoEncoderConfig](#RTCEngine-setvideoencoderconfig) | | abstract int | [setLocalSimulcastMode](#RTCEngine-setlocalsimulcastmode) | | abstract int | [setLocalSimulcastMode](#RTCEngine-setlocalsimulcastmode-2) | | abstract int | [setAudioSourceType](#RTCEngine-setaudiosourcetype) | | abstract int | [setAudioRenderType](#RTCEngine-setaudiorendertype) | | abstract int | [pushExternalAudioFrame](#RTCEngine-pushexternalaudioframe) | | abstract int | [pullExternalAudioFrame](#RTCEngine-pullexternalaudioframe) | | abstract int | [pushReferenceAudioPCMData](#RTCEngine-pushreferenceaudiopcmdata) | | abstract RTCRoom | [createRTCRoom](#RTCEngine-creatertcroom) | | abstract IGameRoom | [createGameRoom](#RTCEngine-creategameroom) | | abstract RTSRoom | [createRTSRoom](#RTCEngine-creatertsroom) | | abstract int | [setPublishFallbackOption](#RTCEngine-setpublishfallbackoption) | | abstract int | [setSubscribeFallbackOption](#RTCEngine-setsubscribefallbackoption) | | abstract int | [setRemoteUserPriority](#RTCEngine-setremoteuserpriority) | | abstract int | [setBusinessId](#RTCEngine-setbusinessid) | | abstract int | [setEncryptInfo](#RTCEngine-setencryptinfo) | | abstract int | [setCustomizeEncryptHandler](#RTCEngine-setcustomizeencrypthandler) | | abstract IVideoEffect | [getVideoEffectInterface](#RTCEngine-getvideoeffectinterface) | | abstract int | [enableEffectBeauty](#RTCEngine-enableeffectbeauty) | | abstract int | [setBeautyIntensity](#RTCEngine-setbeautyintensity) | | abstract int | [setVideoOrientation](#RTCEngine-setvideoorientation) | | abstract int | [setRuntimeParameters](#RTCEngine-setruntimeparameters) | | abstract int | [feedback](#RTCEngine-feedback) | | abstract long | [getNativeHandle](#RTCEngine-getnativehandle) | | abstract int | [startAudioRecording](#RTCEngine-startaudiorecording) | | abstract int | [stopAudioRecording](#RTCEngine-stopaudiorecording) | | abstract IAudioEffectPlayer | [getAudioEffectPlayer](#RTCEngine-getaudioeffectplayer) | | abstract IMediaPlayer | [getMediaPlayer](#RTCEngine-getmediaplayer) | | abstract int | [setScreenAudioSourceType](#RTCEngine-setscreenaudiosourcetype) | | abstract int | [pushScreenAudioFrame](#RTCEngine-pushscreenaudioframe) | | abstract int | [setExternalVideoEncoderEventHandler](#RTCEngine-setexternalvideoencodereventhandler) | | abstract int | [setEarMonitorMode](#RTCEngine-setearmonitormode) | | abstract int | [setEarMonitorMode](#RTCEngine-setearmonitormode-2) | | abstract int | [setEarMonitorVolume](#RTCEngine-setearmonitorvolume) | | abstract int | [enableAudioPropertiesReport](#RTCEngine-enableaudiopropertiesreport) | | abstract int | [sendStreamSyncInfo](#RTCEngine-sendstreamsyncinfo) | | abstract boolean | [isCameraTorchSupported](#RTCEngine-iscameratorchsupported) | | abstract boolean | [isCameraZoomSupported](#RTCEngine-iscamerazoomsupported) | | abstract int | [setCameraZoomRatio](#RTCEngine-setcamerazoomratio) | | abstract float | [getCameraZoomMaxRatio](#RTCEngine-getcamerazoommaxratio) | | abstract int | [setCameraTorch](#RTCEngine-setcameratorch) | | abstract boolean | [isCameraFocusPositionSupported](#RTCEngine-iscamerafocuspositionsupported) | | abstract int | [setCameraFocusPosition](#RTCEngine-setcamerafocusposition) | | abstract boolean | [isCameraExposurePositionSupported](#RTCEngine-iscameraexposurepositionsupported) | | abstract int | [setCameraExposurePosition](#RTCEngine-setcameraexposureposition) | | abstract int | [setCameraExposureCompensation](#RTCEngine-setcameraexposurecompensation) | | abstract int | [enableCameraAutoExposureFaceMode](#RTCEngine-enablecameraautoexposurefacemode) | | abstract int | [setCameraAdaptiveMinimumFrameRate](#RTCEngine-setcameraadaptiveminimumframerate) | | abstract int | [enableAlphaChannelVideoEncode](#RTCEngine-enablealphachannelvideoencode) | | abstract int | [disableAlphaChannelVideoEncode](#RTCEngine-disablealphachannelvideoencode) | | abstract int | [sendSEIMessage](#RTCEngine-sendseimessage) | | abstract int | [startFileRecording](#RTCEngine-startfilerecording) | | abstract int | [stopFileRecording](#RTCEngine-stopfilerecording) | | abstract int | [pushExternalEncodedVideoFrame](#RTCEngine-pushexternalencodedvideoframe) | | abstract int | [startScreenCapture](#RTCEngine-startscreencapture) | | abstract int | [updateScreenCapture](#RTCEngine-updatescreencapture) | | abstract int | [stopScreenCapture](#RTCEngine-stopscreencapture) | | abstract int | [setVideoWatermark](#RTCEngine-setvideowatermark) | | abstract int | [clearVideoWatermark](#RTCEngine-clearvideowatermark) | | abstract int | [setDummyCaptureImagePath](#RTCEngine-setdummycaptureimagepath) | | abstract long | [takeLocalSnapshot](#RTCEngine-takelocalsnapshot) | | abstract long | [takeRemoteSnapshot](#RTCEngine-takeremotesnapshot) | | abstract long | [takeRemoteSnapshotToFile](#RTCEngine-takeremotesnapshottofile) | | abstract long | [takeLocalSnapshotToFile](#RTCEngine-takelocalsnapshottofile) | | abstract int | [startEchoTest](#RTCEngine-startechotest) | | abstract int | [stopEchoTest](#RTCEngine-stopechotest) | | abstract int | [setRemoteVideoSink](#RTCEngine-setremotevideosink-2) | | abstract int | [updateRemoteStreamVideoCanvas](#RTCEngine-updateremotestreamvideocanvas-2) | | abstract int | [setRemoteVideoCanvas](#RTCEngine-setremotevideocanvas) | | abstract int | [setRemoteAudioPlaybackVolume](#RTCEngine-setremoteaudioplaybackvolume) | | abstract int | [setVideoDecoderConfig](#RTCEngine-setvideodecoderconfig) | | abstract int | [requestRemoteVideoKeyFrame](#RTCEngine-requestremotevideokeyframe) | | abstract int | [startCloudProxy](#RTCEngine-startcloudproxy) | | abstract int | [stopCloudProxy](#RTCEngine-stopcloudproxy) | | abstract NetworkTimeInfo | [getNetworkTimeInfo](#RTCEngine-getnetworktimeinfo) | | abstract IWTNStream | [getWTNStream](#RTCEngine-getwtnstream) | | abstract int | [startHardwareEchoDetection](#RTCEngine-starthardwareechodetection) | | abstract int | [stopHardwareEchoDetection](#RTCEngine-stophardwareechodetection) | | abstract int | [setCellularEnhancement](#RTCEngine-setcellularenhancement) | | abstract int | [setLocalProxy](#RTCEngine-setlocalproxy) | | abstract IVideoDeviceManager | [getVideoDeviceManager](#RTCEngine-getvideodevicemanager) | | abstract int | [setVideoCaptureRotation](#RTCEngine-setvideocapturerotation) | | abstract int | [deprecated] [setLocalVideoSink](#RTCEngine-setlocalvideosink) | | abstract int | [deprecated] [setRemoteVideoSink](#RTCEngine-setremotevideosink) | | abstract int | [deprecated] [updateRemoteStreamVideoCanvas](#RTCEngine-updateremotestreamvideocanvas) | ## 函数说明 ### createRTCEngine ```java public static synchronized RTCEngine com.ss.bytertc.engine.RTCEngine.createRTCEngine( EngineConfig config, IRTCEngineEventHandler handler ) ``` 创建引擎对象如果当前进程中未创建引擎实例，那么你必须先使用此方法，以使用 RTC 提供的各种音视频能力。如果当前进程中已创建了引擎实例，再次调用此方法时，会返回已创建的引擎实例。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | config | EngineConfig | SDK 引擎配置参数，详见 [EngineConfig](70083#EngineConfig) | | handler | IRTCEngineEventHandler | SDK 回调给应用层的 Handler，详见 [IRTCEngineEventHandler](70081#IRTCEngineEventHandler) | **返回值** - RTCEngine：创建成功。返回一个可用的 [RTCEngine](#RTCEngine) 实例 - Null：EngineConfig 无效详见 [EngineConfig](70083#EngineConfig) ，so 文件加载失败。 **注意** 你应注意保持 handler 的生命周期必须大于 [RTCEngine](#RTCEngine) 的生命周期，即 handler 必须在调用 [destroyRTCEngine](#RTCEngine-destroyrtcengine) 之后销毁。 ### destroyRTCEngine ```java public static synchronized void com.ss.bytertc.engine.RTCEngine.destroyRTCEngine() ``` 销毁由 [createRTCEngine](#RTCEngine-creatertcengine) 所创建的引擎实例，并释放所有相关资源。 **注意** - 请确保和需要销毁的 [RTCEngine](#RTCEngine) 实例相关的业务场景全部结束后，才调用此方法 - 该方法在调用之后，会销毁所有和此 [RTCEngine](#RTCEngine) 实例相关的内存，并且停止与媒体服务器的任何交互 - 调用本方法会启动 SDK 退出逻辑。引擎线程会保留，直到退出逻辑完成。因此，不要在回调线程中直接调用此 API，会导致死锁。同时此方法是耗时操作，不建议在主线程调用本方法，避免主线程阻塞。 ### getSDKVersion ```java public static String com.ss.bytertc.engine.RTCEngine.getSDKVersion() ``` 获取 SDK 当前的版本号。 **返回值** SDK 当前的版本号。 ### setLogConfig ```java public static int com.ss.bytertc.engine.RTCEngine.setLogConfig(RTCLogConfig logConfig) ``` 配置 SDK 本地日志参数，包括日志级别、存储路径、日志文件最大占用的总空间、日志文件名前缀。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | logConfig | RTCLogConfig | 本地日志参数，参看 [RTCLogConfig](70083#RTCLogConfig)。 | **返回值** - 0：成功。 - –1：失败，本方法必须在创建引擎前调用。 - –2：失败，参数填写错误。 **注意** 本方法必须在调用 [createRTCEngine](#RTCEngine-creatertcengine) 之前调用。 ### getAudioDeviceManager ```java public abstract IRTCAudioDeviceManager com.ss.bytertc.engine.RTCEngine.getAudioDeviceManager() ``` 获取音频设备管理接口 **返回值** 音频设备管理接口 [IRTCAudioDeviceManager](#IRTCAudioDeviceManager) ### startVideoCapture ```java public abstract int com.ss.bytertc.engine.RTCEngine.startVideoCapture() ``` 立即开启内部视频采集。默认为关闭状态。内部视频采集指：使用 RTC SDK 内置视频采集模块，进行采集。调用该方法后，本地用户会收到 [onVideoDeviceStateChanged](70081#IRTCEngineEventHandler-onvideodevicestatechanged) 的回调。本地用户在非隐身状态下调用该方法后，房间中的其他用户会收到 [onUserStartVideoCapture](70081#IRTCEngineEventHandler-onuserstartvideocapture) 的回调。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 自 v3.37.0 版本，使用本接口需要在 Gradle 里引入 Kotlin。 - 调用 [stopVideoCapture](#RTCEngine-stopvideocapture) 可以停止内部视频采集。否则，只有当销毁引擎实例时，内部视频采集才会停止。 - 创建引擎后，无论是否发布视频数据，你都可以调用该方法开启内部视频采集。只有当（内部或外部）视频采集开始以后视频流才会发布。 - 如果需要从自定义视频采集切换为内部视频采集，你必须先停止发布流，关闭自定义采集，再调用此方法手动开启内部采集。 - 内部视频采集使用的摄像头由 [switchCamera](#RTCEngine-switchcamera) 接口指定。 - 你还可以联系技术支持人员，帮助你在服务端配置采集格式并下发到 Android 端。 ### stopVideoCapture ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopVideoCapture() ``` 立即关闭内部视频采集。默认为关闭状态。内部视频采集指：使用 RTC SDK 内置视频采集模块，进行采集。调用该方法，本地用户会收到 [onVideoDeviceStateChanged](70081#IRTCEngineEventHandler-onvideodevicestatechanged) 的回调。非隐身用户进房后调用该方法，房间中的其他用户会收到 [onUserStopVideoCapture](70081#IRTCEngineEventHandler-onuserstopvideocapture) 的回调。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [startVideoCapture](#RTCEngine-startvideocapture) 可以开启内部视频采集。 - 如果不调用本方法停止内部视频采集，则只有当销毁引擎实例时，内部视频采集才会停止。 ### startAudioCapture ```java public abstract int com.ss.bytertc.engine.RTCEngine.startAudioCapture() ``` 开启内部音频采集。默认为关闭状态。内部采集是指：使用 RTC SDK 内置的音频采集机制进行音频采集。调用该方法开启后，本地用户会收到 [onAudioDeviceStateChanged](70081#IRTCEngineEventHandler-onaudiodevicestatechanged) 的回调。非隐身用户进房后调用该方法，房间中的其他用户会收到 [onUserStartAudioCapture](70081#IRTCEngineEventHandler-onuserstartaudiocapture) 的回调。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 若未取得当前设备的麦克风权限，调用该方法后会触发 [onAudioDeviceStateChanged](70081#IRTCEngineEventHandler-onaudiodevicestatechanged) 回调，对应的错误码为 `MediaDeviceError.MEDIA_DEVICE_ERROR_NOPERMISSION = 1`。 - 调用 [stopAudioCapture](#RTCEngine-stopaudiocapture) 可以关闭音频采集设备，否则，SDK 只会在销毁引擎的时候自动关闭设备。 - 由于不同硬件设备初始化响应时间不同，频繁调用 [stopAudioCapture](#RTCEngine-stopaudiocapture) 和本接口闭麦/开麦可能出现短暂无声问题，建议使用 [publishStreamAudio](#RTCRoom-publishstreamaudio) 实现临时闭麦和重新开麦。 - 创建引擎后，无论是否发布音频数据，你都可以调用该方法开启音频采集，并且调用后方可发布音频。 - 如果需要从自定义音频采集切换为内部音频采集，你必须先停止发布流，调用 [setAudioSourceType](#RTCEngine-setaudiosourcetype) 关闭自定义采集，再调用此方法手动开启内部采集。 ### stopAudioCapture ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopAudioCapture() ``` 立即关闭内部音频采集。默认为关闭状态。内部采集是指：使用 RTC SDK 内置的音频采集机制进行音频采集。调用该方法，本地用户会收到 [onAudioDeviceStateChanged](70081#IRTCEngineEventHandler-onaudiodevicestatechanged) 的回调。非隐身用户进房后调用该方法，房间中的其他用户会收到 [onUserStopAudioCapture](70081#IRTCEngineEventHandler-onuserstopaudiocapture) 的回调。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [startAudioCapture](#RTCEngine-startaudiocapture) 可以开启内部音频采集设备。 - 如果不调用本方法停止内部音频采集，则只有当销毁引擎实例时，内部音频采集才会停止。 ### setAudioScenario ```java public abstract int com.ss.bytertc.engine.RTCEngine.setAudioScenario(AudioScenarioType audioScenario) ``` > Available since 3.60. 设置音频场景类型。选择音频场景后，SDK 会自动根据场景切换对应的音量模式（通话音量/媒体音量）和改场景下的最佳音频配置。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audioScenario | AudioScenarioType | 音频场景类型，参看 [AudioScenarioType](70083#AudioScenarioType)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 此接口必须在加入 RTC 房间前调用。 - 通话音量更适合通话、会议等对信息准确度更高的场景。通话音量会激活系统硬件信号处理，使通话声音更清晰。同时，音量无法降低到 0。 - 媒体音量更适合娱乐场景，因其声音的表现力会更强。媒体音量下，最低音量可以为 0。 ### setAudioProfile ```java public abstract int com.ss.bytertc.engine.RTCEngine.setAudioProfile(AudioProfileType audioProfile) ``` 设置音质档位。当所选的 [ChannelProfile](70083#ChannelProfile) 中的音频参数无法满足你的场景需求时，调用本接口切换的音质档位。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audioProfile | AudioProfileType | 音质档位，参看 [AudioProfileType](70083#AudioProfileType) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法在进房前后均可调用； - 支持通话过程中动态切换音质档位。 ### setAnsMode ```java public abstract int com.ss.bytertc.engine.RTCEngine.setAnsMode(AnsMode ansMode) ``` > Available since 3.52 支持根据业务场景，设置通话中的音频降噪模式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | ansMode | AnsMode | 降噪模式。具体参见 [AnsMode](70083#AnsMode)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该接口进房前后均可调用，可重复调用，仅最后一次调用生效。 - 降噪算法包含传统降噪和 AI 降噪。传统降噪主要是抑制平稳噪声，比如空调声、风扇声等。而 AI 降噪主要是抑制非平稳噪声，比如键盘敲击声、桌椅碰撞声等。 - 只有以下 [ChannelProfile](70083#ChannelProfile) 场景时，调用本接口可以开启 AI 降噪。其余场景的 AI 降噪不会生效。 - 游戏语音模式：`CHANNEL_PROFILE_GAME(2)` - 高音质游戏模式：`CHANNEL_PROFILE_GAME_HD(8)` - 云游戏模式：`CHANNEL_PROFILE_CLOUD_GAME(3)` - 1 vs 1 音视频通话：`CHANNEL_PROFILE_CHAT(5)` - 多端同步播放音视频：`CHANNEL_PROFILE_LW_TOGETHER(7)` - 云端会议中的个人设备：`CHANNEL_PROFIEL_MEETING` - 课堂互动模式：`CHANNEL_PROFILE_MEETING_ROOM(17)` - 云端会议中的会议室终端：`CHANNEL_PROFILE_CLASSROOM(18)` ### setVoiceChangerType ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVoiceChangerType(VoiceChangerType voiceChanger) ``` > Available since 3.32 设置变声特效类型 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | voiceChanger | VoiceChangerType | 变声特效类型，参看 [VoiceChangerType](70083#VoiceChangerType) | **返回值** 方法调用结果： - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** - 如需使用该功能，需集成 SAMI 动态库，详情参看[按需集成插件](1108726)文档。 - 在进房前后都可设置。 - 对 RTC SDK 内部采集的音频和自定义采集的音频都生效。 - 只对单声道音频生效。 - 与 [setVoiceReverbType](#RTCEngine-setvoicereverbtype) 互斥，后设置的特效会覆盖先设置的特效。 ### setVoiceReverbType ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVoiceReverbType(VoiceReverbType voiceReverb) ``` > Available since 3.32 设置混响特效类型 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | voiceReverb | VoiceReverbType | 混响特效类型，参看 [VoiceReverbType](70083#VoiceReverbType) | **返回值** 方法调用结果： - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** - 在进房前后都可设置。 - 对 RTC SDK 内部采集的音频和自定义采集的音频都生效。 - 只对单声道音频生效。 - 与 [setVoiceChangerType](#RTCEngine-setvoicechangertype) 互斥，后设置的特效会覆盖先设置的特效。 ### setLocalVoiceEqualization ```java public abstract int com.ss.bytertc.engine.RTCEngine.setLocalVoiceEqualization(VoiceEqualizationConfig voiceEqualizationConfig) ``` 设置本地采集语音的均衡效果。包含内部采集和外部采集，但不包含混音音频文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | voiceEqualizationConfig | VoiceEqualizationConfig | 语音均衡效果，参看 [VoiceEqualizationConfig](70083#VoiceEqualizationConfig) | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 根据奈奎斯特采样率，音频采样率必须大于等于设置的中心频率的两倍，否则，设置不生效。 ### setLocalVoiceReverbParam ```java public abstract int com.ss.bytertc.engine.RTCEngine.setLocalVoiceReverbParam(VoiceReverbConfig config) ``` 设置本地采集音频的混响效果。包含内部采集和外部采集，但不包含混音音频文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | config | VoiceReverbConfig | 混响效果，参看 [VoiceReverbConfig](70083#VoiceReverbConfig) | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 调用 [enableLocalVoiceReverb](#RTCEngine-enablelocalvoicereverb) 开启混响效果。 ### enableLocalVoiceReverb ```java public abstract int com.ss.bytertc.engine.RTCEngine.enableLocalVoiceReverb(boolean enable) ``` 开启本地音效混响效果 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 是否开启 | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 调用 [setLocalVoiceReverbParam](#RTCEngine-setlocalvoicereverbparam) 设置混响效果。 ### setLocalVideoCanvas ```java public abstract int com.ss.bytertc.engine.RTCEngine.setLocalVideoCanvas(VideoCanvas videoCanvas) ``` 设置本地视频渲染时使用的视图，并设置渲染模式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | videoCanvas | VideoCanvas | 视图信息和渲染模式, 参看 [VideoCanvas](70083#VideoCanvas) | **返回值** - 0：成功 - -2：参数错误。 - -12：本方法不支持在 Audio SDK 中使用。 **注意** - 你应在加入房间前，绑定本地视图。退出房间后，此设置仍然有效。 - 如果需要解除绑定，你可以调用本方法传入空视图。 ### updateLocalVideoCanvas ```java public abstract int com.ss.bytertc.engine.RTCEngine.updateLocalVideoCanvas( int renderMode, int backgroundColor ) ``` 修改本地视频渲染模式和背景色。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | renderMode | int | 渲染模式。参看 [VideoCanvas](70083#VideoCanvas).renderMode | | backgroundColor | int | 背景颜色。参看 [VideoCanvas](70083#VideoCanvas).backgroundColor | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 你可以在本地视频渲染过程中，调用此接口。调用结果会实时生效。 ### setLocalVideoSink ```java public abstract int com.ss.bytertc.engine.RTCEngine.setLocalVideoSink( IVideoSink videoSink, LocalVideoSinkConfig config ) ``` > Available since 3.57 将本地视频流与自定义渲染器绑定。你可以通过参数设置返回指定位置和格式的视频帧数据。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | videoSink | IVideoSink | 自定义视频渲染器，参看 [IVideoSink](70083#IVideoSink)。 | | config | LocalVideoSinkConfig | 本地视频帧回调配置，参看 [LocalVideoSinkConfig](70083#LocalVideoSinkConfig)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - RTC SDK 默认使用自带的渲染器（内部渲染器）进行视频渲染。 - 退房时将清除绑定状态。 - 如果需要解除绑定，你必须将 videoSink 设置为 null。 - 一般在收到 [onFirstLocalVideoFrameCaptured](70081#IRTCEngineEventHandler-onfirstlocalvideoframecaptured) 回调通知完成本地视频首帧采集后，调用此方法为视频流绑定自定义渲染器；然后加入房间。 ### setLocalVideoMirrorType ```java public abstract int com.ss.bytertc.engine.RTCEngine.setLocalVideoMirrorType(MirrorType mirrorType) ``` 为采集到的视频流开启镜像 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mirrorType | MirrorType | 镜像类型，参看 [MirrorType](70083#MirrorType) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 切换视频源不影响镜像设置。 - 屏幕视频流始终不受镜像设置影响。 - 使用外部渲染器时，`mirrorType` 支持设置为 `0`（无镜像）和 `3`（本地预览和编码传输镜像），不支持设置为 `1`（本地预览镜像）。 - 该接口调用前，各视频源的初始状态如下：

	前置摄像头	后置摄像头	自定义采集视频源	桌面端摄像头
移动端	本地预览镜像，编码传输不镜像	本地预览不镜像，编码传输不镜像	本地预览不镜像，编码传输不镜像	/
桌面端	/	/	本地预览不镜像，编码传输不镜像	本地预览镜像，编码传输不镜像

### setRemoteVideoMirrorType ```java public abstract int com.ss.bytertc.engine.RTCEngine.setRemoteVideoMirrorType( String streamId, RemoteMirrorType mirrorType ) ``` > Available since 3.57 使用内部渲染时，为远端流开启镜像。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 流 ID，用于指定需要镜像的视频流。 | | mirrorType | RemoteMirrorType | 远端流的镜像类型，参看 [RemoteMirrorType](70083#RemoteMirrorType)。 | **返回值** - 0：调用成功。 - < 0：调用失败，参看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### setVideoRotationMode ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVideoRotationMode(VideoRotationMode rotationMode) ``` 设置采集视频的旋转模式。默认以 App 方向为旋转参考系。接收端渲染视频时，将按照和发送端相同的方式进行旋转。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | rotationMode | VideoRotationMode | 视频旋转参考系为 App 方向或重力方向，参看 [VideoRotationMode](70083#VideoRotationMode)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 旋转仅对内部视频采集生效，不适用于外部视频源和屏幕源。 - 调用该接口时已开启视频采集，将立即生效；调用该接口时未开启视频采集，则将在采集开启后生效。 - 更多信息请参考[视频采集方向](https://www.volcengine.com/docs/6348/106458)。 ### switchCamera ```java public abstract int com.ss.bytertc.engine.RTCEngine.switchCamera(CameraId cameraId) ``` 切换视频内部采集时使用的前置/后置摄像头调用此接口后，在本地会触发 [onVideoDeviceStateChanged](70081#IRTCEngineEventHandler-onvideodevicestatechanged) 回调。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | cameraId | CameraId | 摄像头 ID，参看 [CameraId](70083#CameraId) | **返回值** - 0：方法调用成功 - < 0：方法调用失败 **注意** - 默认使用前置摄像头。 - 如果你正在使用相机进行视频采集，切换操作当即生效；如果相机未启动，后续开启内部采集时，会打开设定的摄像头。 ### setAudioRoute ```java public abstract int com.ss.bytertc.engine.RTCEngine.setAudioRoute(AudioRoute audioRoute) ``` 强制切换当前的音频播放路由。默认使用 [setDefaultAudioRoute](#RTCEngine-setdefaultaudioroute) 中设置的音频路由。音频播放路由发生变化时，会收到 [onAudioRouteChanged](70081#IRTCEngineEventHandler-onaudioroutechanged) 回调。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audioRoute | AudioRoute | 音频播放路由，参见 [AudioRoute](70083#AudioRoute)。
对 Android 设备，不同的音频设备连接状态下，可切换的音频设备情况不同。参见[移动端设置音频路由](https://www.volcengine.com/docs/6348/117836)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 对于绝大多数音频场景，推荐使用 [setDefaultAudioRoute](#RTCEngine-setdefaultaudioroute) 设置默认音频路由，并借助 RTC SDK 的音频路由自动切换逻辑即可完成。切换逻辑参见[移动端设置音频路由](https://www.volcengine.com/docs/6348/117836)。你应仅在例外的场景下，使用此接口，比如在接入外接音频设备时，手动切换音频路由。 - 本接口仅支持在通话模式下使用。 - 不同音频场景中，音频路由和发布订阅状态到音量类型的映射关系详见 [AudioScenarioType](70083#AudioScenarioType) 。 ### getAudioRoute ```java public abstract AudioRoute com.ss.bytertc.engine.RTCEngine.getAudioRoute() ``` 获取当前使用的音频播放路由。 **返回值** 详见 [AudioRoute](70083#AudioRoute) **注意** 要设置音频路由，详见 [setAudioRoute](#RTCEngine-setaudioroute)。 ### setDefaultAudioRoute ```java public abstract int com.ss.bytertc.engine.RTCEngine.setDefaultAudioRoute(AudioRoute route) ``` 将默认的音频播放设备设置为听筒或扬声器。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | route | AudioRoute | 音频播放设备。参看 [AudioRoute](70083#AudioRoute)。仅支持听筒或扬声器。 | **返回值** - 0：方法调用成功。 - < 0：方法调用失败。 **注意** 对于音频路由切换逻辑，参见[移动端设置音频路由](https://www.volcengine.com/docs/6348/117836)。 ### enableExternalSoundCard ```java public abstract int com.ss.bytertc.engine.RTCEngine.enableExternalSoundCard(boolean enable) ``` 启用匹配外置声卡的音频处理模式 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean |

true：开启
false：不开启(默认)

| **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 当采用外接声卡进行音频采集时，建议开启此模式，以获得更好的音质。 - 开启此模式时，仅支持耳机播放。如果需要使用扬声器或者外置音箱播放，关闭此模式。 ### muteAudioCapture ```java public abstract int com.ss.bytertc.engine.RTCEngine.muteAudioCapture(boolean mute) ``` > Available since 3.58.1 设置是否将采集到的音频信号静音，而不影响改变本端硬件采集状态。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mute | boolean | 是否静音音频采集。

True：静音（关闭麦克风）
False：（默认）开启麦克风

| **返回值** - 0：调用成功。 - < 0：调用失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** - 该方法用于设置是否使用静音数据替换设备采集到的音频数据进行推流，不影响 SDK 音频流的采集发布状态。 - 静音后通过 [setCaptureVolume](#RTCEngine-setcapturevolume) 调整音量不会取消静音状态，音量状态会保存至取消静音。 - 调用 [startAudioCapture](#RTCEngine-startaudiocapture) 开启音频采集前后，都可以使用此接口设置采集音量。 ### muteScreenAudioCapture ```java public abstract int com.ss.bytertc.engine.RTCEngine.muteScreenAudioCapture(boolean mute) ``` > Available since 3.60. 静音/取消静音屏幕共享时采集的音频。调用此方法后，SDK 将发送静音数据来代替真实的屏幕音频数据，不影响本端音频设备的采集状态和 SDK 音频流的采集发布状态。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mute | boolean | 是否静音屏幕音频。

True：静音。远端用户听不到来自你屏幕共享的声音。
False：（默认）取消静音。恢复发送屏幕共享的音频。

| **返回值** - 0：调用成功。 - < 0：调用失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** - 静音后通过 [setCaptureVolume](#RTCEngine-setcapturevolume) 调整音量不会取消静音状态，音量状态会保存至取消静音。 - 调用 [startAudioCapture](#RTCEngine-startaudiocapture) 开启音频采集前后，都可以使用此接口设置采集音量。 ### setCaptureVolume ```java public abstract int com.ss.bytertc.engine.RTCEngine.setCaptureVolume(int volume) ``` 调节音频采集音量 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 采集的音量值和原始音量的百分比，范围是 [0, 400]，单位为 \%，自带溢出保护。
只改变音频数据的音量信息，不涉及本端硬件的音量调节。
为保证更好的通话质量，建议将 volume 值设为 [0,100]。

0：静音
100：原始音量
400：最大可为原始音量的 4 倍(自带溢出保护)

| **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 在开启音频采集前后，你都可以使用此接口设定采集音量。 ### setScreenCaptureVolume ```java public abstract int com.ss.bytertc.engine.RTCEngine.setScreenCaptureVolume(int volume) ``` > Available Available since 3.60. 调节屏幕共享时采集的音频音量。只改变音频数据的音量信息，不影响麦克风采集的音量，也不会改变本端音频设备本身的音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 采集的音量值和原始音量的百分比，范围是 [0, 400]，单位为 \%，自带溢出保护。
为保证更好的通话质量，建议将 volume 值设为 [0, 100]。

0：静音
100：原始音量
400：最大可为原始音量的 4 倍(自带溢出保护)

| **返回值** + 0：调用成功。 + < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 在开启屏幕音频采集前后，你都可以使用此接口设定采集音量。 ### setPlaybackVolume ```java public abstract int com.ss.bytertc.engine.RTCEngine.setPlaybackVolume(int volume) ``` 调节本地播放的所有远端用户音频混音后的音量，混音内容包括远端人声、音乐、音效等。播放音频前或播放音频时，你都可以使用此接口设定播放音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 音频播放音量值和原始音量的比值，范围是 [0, 400]，单位为 \%，自带溢出保护。
为保证更好的通话质量，建议将 volume 值设为 [0,100]。

0：静音
100：原始音量
400：最大可为原始音量的 4 倍(自带溢出保护)

| **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 假设某远端用户 A 始终在被调节的目标用户范围内，当该方法与 [setRemoteAudioPlaybackVolume](#RTCEngine-setremoteaudioplaybackvolume) 或 [setRemoteRoomAudioPlaybackVolume](#RTCRoom-setremoteroomaudioplaybackvolume) 共同使用时，本地收听用户 A 的音量将为两次设置的音量效果的叠加。 ### setLocalVoicePitch ```java public abstract int com.ss.bytertc.engine.RTCEngine.setLocalVoicePitch(int pitch) ``` 开启本地语音变调功能，多用于 K 歌场景。使用该方法，你可以对本地语音的音调进行升调或降调等调整。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | pitch | int | 相对于语音原始音调的升高/降低值，取值范围[-12，12]，默认值为 0，即不做调整。
取值范围内每相邻两个值的音高距离相差半音，正值表示升调，负值表示降调，设置的绝对值越大表示音调升高或降低越多。
超出取值范围则设置失败，并且会触发 [onWarning](70081#IRTCEngineEventHandler-onwarning) 回调，提示 [WarningCode](70082#WarningCode) 错误码为 `WARNING_CODE_SET_SCREEN_STREAM_INVALID_VOICE_PITCH` 设置语音音调不合法 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### enableVocalInstrumentBalance ```java public abstract int com.ss.bytertc.engine.RTCEngine.enableVocalInstrumentBalance(boolean enable) ``` 开启/关闭音量均衡功能。开启音量均衡功能后，人声的响度会调整为 -16lufs。如果已调用 setAudioMixingLoudness 传入了混音音乐的原始响度，此音乐播放时，响度会调整为 -20lufs。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 是否开启音量均衡功能：

true：是
false：否

| **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 该接口须在调用 [start](#IAudioEffectPlayer-start) 开始播放音频文件之前调用。 ### enablePlaybackDucking ```java public abstract int com.ss.bytertc.engine.RTCEngine.enablePlaybackDucking(boolean enable) ``` 打开/关闭音量闪避功能，适用于在 RTC 通话过程中会同时播放短视频或音乐的场景，如“一起看”等。开启该功能后，当检测到远端人声时，RTC 的本地的媒体播放音量会自动减弱，从而保证远端人声的清晰可辨；当远端人声消失时，RTC 的本地媒体音量会恢复到闪避前的音量水平。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 是否开启音量闪避：

true：是
false：否

| **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### login ```java public abstract int com.ss.bytertc.engine.RTCEngine.login( String token, String uid ) ``` 登录 RTS 服务器。必须先登录，才能调用 [sendUserMessageOutsideRoom](#RTCEngine-sendusermessageoutsideroom) 和 [sendServerMessage](#RTCEngine-sendservermessage) 发送房间外点对点消息和向应用服务器发送消息在调用本接口登录后，如果想要登出，需要调用 [logout](#RTCEngine-logout)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | String | 用户登录必须携带的 Token，用于鉴权验证。
测试时可使用[控制台](https://console.volcengine.com/rtc/listRTC)生成临时 Token，`roomId` 填任意值。
正式上线需要使用密钥 SDK 在你的服务端生成并下发 Token，`roomId` 置空，Token 有效期及生成方式参看[使用 Token 完成鉴权](70121)。 | | uid | String | 用户 ID
用户 ID 在 appid 的维度下是唯一的。 | **返回值** - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** 本地用户调用此方法登录成功后，会收到 [onLoginResult](70081#IRTCEngineEventHandler-onloginresult) 回调通登录结果，远端用户不会收到通知。 ### logout ```java public abstract int com.ss.bytertc.engine.RTCEngine.logout() ``` 登出 RTS 服务器。调用本接口登出后，无法调用房间外消息以及端到服务器消息相关的方法或收到相关回调。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用本接口登出后，必须先调用 [login](#RTCEngine-login) 登录。 - 本地用户调用此方法登出后，会收到 [onLogout](70081#IRTCEngineEventHandler-onlogout) 回调通知结果，远端用户不会收到通知。 ### updateLoginToken ```java public abstract int com.ss.bytertc.engine.RTCEngine.updateLoginToken(String token) ``` 更新用户用于登录的 Token Token 有一定的有效期，当 Token 过期时，需调用此方法更新登录的 Token 信息。调用 [login](#RTCEngine-login) 方法登录时，如果使用了过期的 Token 将导致登录失败，并会收到 [onLoginResult](70081#IRTCEngineEventHandler-onloginresult) 回调通知，错误码为 `LOGIN_ERROR_CODE_INVALID_TOKEN`。此时需要重新获取 Token，并调用此方法更新 Token。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | String | 更新的动态密钥 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 如果 Token 无效导致登录失败，则调用此方法更新 Token 后，SDK 会自动重新登录，而用户不需要自己调用 [login](#RTCEngine-login) 方法。 - Token 过期时，如果已经成功登录，则不会受到影响。Token 过期的错误会在下一次使用过期 Token 登录时，或因本地网络状况不佳导致断网重新登录时通知给用户。 ### setServerParams ```java public abstract int com.ss.bytertc.engine.RTCEngine.setServerParams( String signature, String url ) ``` 设置应用服务器参数客户端调用 [sendServerMessage](#RTCEngine-sendservermessage) 或 [sendServerBinaryMessage](#RTCEngine-sendserverbinarymessage) 发送消息给应用服务器之前，必须需要设置有效签名和应用服务器地址。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | signature | String | 动态签名，应用服务器可使用该签名验证消息来源。
签名需自行定义，可传入任意非空字符串，建议将 uid 等信息编码为签名。
设置的签名会以 post 形式发送至通过本方法中 url 参数设置的应用服务器地址。 | | url | String | 应用服务器的地址 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 用户必须调用 [login](#RTCEngine-login) 登录后，才能调用本接口。 - 调用本接口后，SDK 会使用 [onServerParamsSetResult](70081#IRTCEngineEventHandler-onserverparamssetresult) 返回相应结果。 ### getPeerOnlineStatus ```java public abstract int com.ss.bytertc.engine.RTCEngine.getPeerOnlineStatus(String peerUserID) ``` 查询对端用户或本端用户的登录状态 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | peerUserID | String | 需要查询的用户 ID | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 必须调用 [login](#RTCEngine-login) 登录后，才能调用本接口。 - 调用本接口后，SDK 会使用 [onGetPeerOnlineStatus](70081#IRTCEngineEventHandler-ongetpeeronlinestatus) 回调通知查询结果。 - 在发送房间外消息之前，用户可以通过本接口了解对端用户是否登录，从而决定是否发送消息。也可以通过本接口查询自己查看自己的登录状态。 ### sendUserMessageOutsideRoom ```java public abstract long com.ss.bytertc.engine.RTCEngine.sendUserMessageOutsideRoom( String uid, String message, MessageConfig config ) ``` 给房间外指定的用户发送文本消息（P2P） **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | uid | String | 消息接收用户的 ID | | message | String | 发送的文本消息内容。
消息不超过 64 KB。 | | config | MessageConfig | 消息类型，参看 [MessageConfig](70083#MessageConfig)。 | **返回值** - \>0：发送成功，返回这次发送消息的编号，从 1 开始递增。 **注意** - 在发送房间外文本消息前，必须先调用 [login](#RTCEngine-login) 完成登录。 - 用户调用本接口发送文本信息后，会收到一次 [onUserMessageSendResultOutsideRoom](70081#IRTCEngineEventHandler-onusermessagesendresultoutsideroom) 回调，得知消息是否成功发送。 - 若文本消息发送成功，则 uid 所指定的用户会通过 [onUserMessageReceivedOutsideRoom](70081#IRTCEngineEventHandler-onusermessagereceivedoutsideroom) 回调收到该消息。 ### sendUserBinaryMessageOutsideRoom ```java public abstract long com.ss.bytertc.engine.RTCEngine.sendUserBinaryMessageOutsideRoom( String uid, byte[] buffer, MessageConfig config ) ``` 给房间外指定的用户发送二进制消息（P2P） **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | uid | String | 消息接收用户的 ID | | buffer | byte[] | 发送的二进制消息内容
消息不超过 64KB。 | | config | MessageConfig | 消息类型，参看 [MessageConfig](70083#MessageConfig)。 | **返回值** - \>0：发送成功，返回这次发送消息的编号，从 1 开始递增。 - -1：发送失败。消息为空。 **注意** - 在发送房间外二进制消息前，必须先调用 [login](#RTCEngine-login) 完成登录。 - 用户调用本接口发送二进制消息后，会收到一次 [onUserMessageSendResultOutsideRoom](70081#IRTCEngineEventHandler-onusermessagesendresultoutsideroom) 回调，通知消息是否发送成功； - 若二进制消息发送成功，则 uid 所指定的用户会通过 [onUserBinaryMessageReceivedOutsideRoom](70081#IRTCEngineEventHandler-onuserbinarymessagereceivedoutsideroom) 回调收到该条消息。 ### sendServerMessage ```java public abstract long com.ss.bytertc.engine.RTCEngine.sendServerMessage(String message) ``` 客户端给应用服务器发送文本消息（P2Server） **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | message | String | 发送的文本消息内容
消息不超过 64 KB。 | **返回值** - \>0：发送成功，返回这次发送消息的编号，从 1 开始递增。 **注意** - 在向应用服务器发送文本消息前，必须先调用 [login](#RTCEngine-login) 完成登录，随后调用 [setServerParams](#RTCEngine-setserverparams) 设置应用服务器。 - 调用本接口后会收到一次 [onServerMessageSendResult](70081#IRTCEngineEventHandler-onservermessagesendresult) 回调，通知消息发送方是否发送成功。 - 若文本消息发送成功，则之前调用 [setServerParams](#RTCEngine-setserverparams) 设置的应用服务器会收到该条消息。 ### sendServerBinaryMessage ```java public abstract long com.ss.bytertc.engine.RTCEngine.sendServerBinaryMessage(byte[] buffer) ``` 客户端给应用服务器发送二进制消息（P2Server） **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | buffer | byte[] | 发送的二进制消息内容
消息不超过 64KB。 | **返回值** - \>0：发送成功，返回这次发送消息的编号，从 1 开始递增。 - -1：发送失败。消息为空。 **注意** - 在向应用服务器发送二进制消息前，必须先调用 [login](#RTCEngine-login) 完成登录，随后调用 [setServerParams](#RTCEngine-setserverparams) 设置应用服务器。 - 调用本接口后，会收到一次 [onServerMessageSendResult](70081#IRTCEngineEventHandler-onservermessagesendresult) 回调，通知消息发送方发送成功或失败； - 若二进制消息发送成功，则之前调用 [setServerParams](#RTCEngine-setserverparams) 设置的应用服务器会收到该条消息。 ### startNetworkDetection ```java public abstract int com.ss.bytertc.engine.RTCEngine.startNetworkDetection( boolean isTestUplink, int expectedUplinkBitrate, boolean isTestDownlink, int expectedDownlinkBitrate ) ``` 开启通话前网络探测 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | isTestUplink | boolean | 是否探测上行带宽 | | expectedUplinkBitrate | int | 期望上行带宽，单位：kbps
范围为 `{0, [100-10000]}`，其中， `0` 表示由 SDK 指定最高码率。 | | isTestDownlink | boolean | 是否探测下行带宽 | | expectedDownlinkBitrate | int | 期望下行带宽，单位：kbps
范围为 `{0, [100-10000]}`，其中， `0` 表示由 SDK 指定最高码率。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 成功调用本接口后，会在 3s 内收到一次 [onNetworkDetectionResult](70081#IRTCEngineEventHandler-onnetworkdetectionresult) 回调，此后每 2s 收到一次该回调，通知探测结果； - 若探测停止，则会收到一次 [onNetworkDetectionStopped](70081#IRTCEngineEventHandler-onnetworkdetectionstopped) 通知探测停止。 ### stopNetworkDetection ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopNetworkDetection() ``` 停止通话前网络探测 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用本接口后，会收到一次 [onNetworkDetectionStopped](70081#IRTCEngineEventHandler-onnetworkdetectionstopped) 回调通知探测停止。 ### enableAudioFrameCallback ```java public abstract int com.ss.bytertc.engine.RTCEngine.enableAudioFrameCallback( AudioFrameCallbackMethod method, AudioFormat format ) ``` 设置并开启指定的音频数据帧回调 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | method | AudioFrameCallbackMethod | 音频回调方法，参看 [AudioFrameCallbackMethod](70083#AudioFrameCallbackMethod)。
当音频回调方法设置为 `AUDIO_FRAME_CALLBACK_RECORD(0)`、`AUDIO_FRAME_CALLBACK_PLAYBACK(1)`、`AUDIO_FRAME_CALLBACK_MIXED(2)`、 `AUDIO_FRAME_CALLBACK_CAPTURE_MIXED(5)` 时，你需要在参数 `format` 中指定准确的采样率和声道，暂不支持设置为自动。
当音频回调方法设置为 `AUDIO_FRAME_CALLBACK_REMOTE_USER(3)`时，将 `format` 中的各个字段设置为默认值。 | | format | AudioFormat | 音频参数格式，参看 [AudioFormat](70083#AudioFormat)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 开启音频回调并调用 [registerAudioFrameObserver](#RTCEngine-registeraudioframeobserver) 后，[IAudioFrameObserver](70081#IAudioFrameObserver) 会收到对应的音频回调。两者调用顺序没有限制且相互独立。 ### disableAudioFrameCallback ```java public abstract int com.ss.bytertc.engine.RTCEngine.disableAudioFrameCallback(AudioFrameCallbackMethod method) ``` 关闭音频回调 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | method | AudioFrameCallbackMethod | 音频回调方法，参看 [AudioFrameCallbackMethod](70083#AudioFrameCallbackMethod)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 该方法需要在调用 [enableAudioFrameCallback](#RTCEngine-enableaudioframecallback) 之后调用。 ### registerAudioFrameObserver ```java public abstract int com.ss.bytertc.engine.RTCEngine.registerAudioFrameObserver(IAudioFrameObserver observer) ``` 注册音频数据回调观察者。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | observer | IAudioFrameObserver | 音频数据观察者，参看 [IAudioFrameObserver](70081#IAudioFrameObserver)。如果传入 null，则取消注册。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 注册音频数据回调观察者并调用 [enableAudioFrameCallback](#RTCEngine-enableaudioframecallback) 后，[IAudioFrameObserver](70081#IAudioFrameObserver) 会收到对应的音频回调。对回调中收到的音频数据进行处理，不会影响 RTC 的编码发送或渲染。 ### registerAudioProcessor ```java public abstract int com.ss.bytertc.engine.RTCEngine.registerAudioProcessor(IAudioFrameProcessor processor) ``` 注册自定义音频处理器。注册完成后，你可以调用 [enableAudioProcessor](#RTCEngine-enableaudioprocessor)，对本地采集到的音频进行处理，RTC SDK 将对处理后的音频进行编码和发送。也可以对接收到的远端音频进行自定义处理，RTC SDK 将对处理后的音频进行渲染。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | processor | IAudioFrameProcessor | 自定义音频处理器，详见 [IAudioFrameProcessor](70081#IAudioFrameProcessor)。
SDK 只持有 processor 的弱引用，你应保证其生命周期。需要取消注册时，设置此参数为 nullptr。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 重复调用此接口时，仅最后一次调用生效。 - 更多相关信息，详见[音频自定义处理](https://www.volcengine.com/docs/6348/80635)。 ### enableAudioProcessor ```java public abstract int com.ss.bytertc.engine.RTCEngine.enableAudioProcessor( AudioProcessorMethod method, AudioFormat format ) ``` 设置并开启指定的音频帧回调，进行自定义处理。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | method | AudioProcessorMethod | 音频帧类型，参看 [AudioProcessorMethod](70083#AudioProcessorMethod)。可多次调用此接口，处理不同类型的音频帧。
选择不同类型的音频帧将收到对应的回调：

选择本地采集的音频时，会收到 [onProcessRecordAudioFrame](70081#IAudioFrameProcessor-onprocessrecordaudioframe)。
选择远端音频流的混音音频时，会收到 [onProcessPlayBackAudioFrame](70081#IAudioFrameProcessor-onprocessplaybackaudioframe)。
选择远端音频流时，会收到 [onProcessRemoteUserAudioFrame](70081#IAudioFrameProcessor-onprocessremoteuseraudioframe)。
选择软件耳返音频时，会收到 [onProcessEarMonitorAudioFrame](70081#IAudioFrameProcessor-onprocessearmonitoraudioframe)。
选择屏幕共享音频流时，会收到 [onProcessScreenAudioFrame](70081#IAudioFrameProcessor-onprocessscreenaudioframe)。

| | format | AudioFormat | 设定自定义处理时获取的音频帧格式，参看 [AudioFormat](70083#AudioFormat)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 在调用此接口前，你需要调用 [registerAudioProcessor](#RTCEngine-registeraudioprocessor) 注册自定义音频处理器。 - 要关闭音频自定义处理，调用 [disableAudioProcessor](#RTCEngine-disableaudioprocessor)。 ### disableAudioProcessor ```java public abstract int com.ss.bytertc.engine.RTCEngine.disableAudioProcessor(AudioProcessorMethod method) ``` 关闭自定义音频处理。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | method | AudioProcessorMethod | 音频帧类型，参看 [AudioProcessorMethod](70083#AudioProcessorMethod)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### registerLocalVideoProcessor ```java public abstract int com.ss.bytertc.engine.RTCEngine.registerLocalVideoProcessor( IVideoProcessor processor, VideoPreprocessorConfig config ) ``` 设置自定义视频前处理器。使用这个视频前处理器，你能够调用 [processVideoFrame](#IVideoProcessor-processvideoframe) 对 RTC SDK 采集得到的视频帧进行前处理，并将处理后的视频帧用于 RTC 音视频通信。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | processor | IVideoProcessor | 自定义视频处理器，详见 [IVideoProcessor](#IVideoProcessor)。如果传入 null，则不对 RTC SDK 采集得到的视频帧进行前处理。
SDK 只持有 processor 的弱引用，你应保证其生命周期。 | | config | VideoPreprocessorConfig | 自定义视频前处理器适用的设置，详见 [VideoPreprocessorConfig](70083#VideoPreprocessorConfig)。
当前，`config` 中的 `required_pixel_format` 仅支持：`I420`、`TEXTURE_2D` 和 `Unknown`：

设置为 `Unknown` 时，RTC SDK 给出供 processor 处理的视频帧格式即采集的格式。
你可以通过 [pixelFormat](70083#IVideoFrame-pixelformat) 获取实际采集的视频帧格式，支持的格式为：`kVideoPixelFormatI420`、 `kVideoPixelFormatTexture2D` 和 `kVideoPixelFormatTextureOES`
设置为 `I420` 或 `TEXTURE_2D` 时，RTC SDK 会将采集得到的视频转变为对应的格式，供前处理使用。
设置为其他值时，此方法调用失败。

| **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 经前处理后，返回给 RTC SDK 的视频帧格式仅支持 `I420` 和 `TEXTURE_2D`。 ### setVideoDigitalZoomConfig ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVideoDigitalZoomConfig( ZoomConfigType type, float size ) ``` > Available since 3.51 设置本地摄像头数码变焦参数，包括缩放倍数，移动步长。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | ZoomConfigType | 数码变焦参数类型，缩放系数或移动步长。参看 [ZoomConfigType](70083#ZoomConfigType)。必填。 | | size | float | 缩放系数或移动步长，保留到小数点后三位。默认值为 0。必填。
选择不同 `type` 时有不同的取值范围。当计算后的结果超过缩放和移动边界时，取临界值。

`ZOOM_FOCUS_OFFSET(0)`：缩放系数增量，范围为 [0, 7]。例如，设置为 0.5 时，如果调用 [setVideoDigitalZoomControl](#RTCEngine-setvideodigitalzoomcontrol) 选择 Zoom in，则缩放系数增加 0.5。缩放系数范围 [1，8]，默认为 `1`，原始大小。
`ZOOM_MOVE_OFFSET(1)`：移动百分比，范围为 [0, 0.5]，默认为 0，不移动。如果调用 [setVideoDigitalZoomControl](#RTCEngine-setvideodigitalzoomcontrol) 选择的是左右移动，则移动距离为 size x 原始视频宽度；如果选择的是上下移动，则移动距离为 size x 原始视频高度。例如，视频帧边长为 1080 px，设置为 0.5 时，实际移动距离为 0.5 x 1080 px = 540 px。

| **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 每次调用本接口只能设置一种参数。如果缩放系数和移动步长都需要设置，分别调用本接口传入相应参数。 - 由于移动步长的默认值为 `0` ，在调用 [setVideoDigitalZoomControl](#RTCEngine-setvideodigitalzoomcontrol) 或 [startVideoDigitalZoomControl](#RTCEngine-startvideodigitalzoomcontrol) 进行数码变焦操作前，应先调用本接口。 ### setVideoDigitalZoomControl ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVideoDigitalZoomControl(ZoomDirectionType direction) ``` > Available since 3.51 控制本地摄像头数码变焦，缩放或移动一次。设置对本地预览画面和发布到远端的视频都生效。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | direction | ZoomDirectionType | 数码变焦操作类型，参看 [ZoomDirectionType](70083#ZoomDirectionType)。 | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 由于默认步长为 `0`，调用该方法前需通过 [setVideoDigitalZoomConfig](#RTCEngine-setvideodigitalzoomconfig) 设置参数。 - 调用该方法进行移动前，应先使用本方法或 [startVideoDigitalZoomControl](#RTCEngine-startvideodigitalzoomcontrol) 进行放大，否则无法移动。 - 当数码变焦操作超出范围时，将置为临界值。例如，移动到了图片边界、放大到了 8 倍、缩小到原图大小。 - 如果你希望实现持续数码变焦操作，调用 [startVideoDigitalZoomControl](#RTCEngine-startvideodigitalzoomcontrol)。 - 如果你需要对摄像头进行光学变焦控制，参看 [setCameraZoomRatio](#RTCEngine-setcamerazoomratio)。 ### startVideoDigitalZoomControl ```java public abstract int com.ss.bytertc.engine.RTCEngine.startVideoDigitalZoomControl(ZoomDirectionType direction) ``` > Available since 3.51 开启本地摄像头持续数码变焦，缩放或移动。设置对本地预览画面和发布到远端的视频都生效。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | direction | ZoomDirectionType | 数码变焦操作类型，参看 [ZoomDirectionType](70083#ZoomDirectionType)。 | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 由于默认步长为 `0`，调用该方法前需通过 [setVideoDigitalZoomConfig](#RTCEngine-setvideodigitalzoomconfig) 设置参数。 - 调用该方法进行移动前，应先使用本方法或 [setVideoDigitalZoomControl](#RTCEngine-setvideodigitalzoomcontrol) 进行放大，否则无法移动。 - 当数码变焦操作超出范围时，将置为临界值并停止操作。例如，移动到了图片边界、放大到了 8 倍、缩小到原图大小。 - 你也可以调用 [stopVideoDigitalZoomControl](#RTCEngine-stopvideodigitalzoomcontrol) 手动停止控制。 - 如果你希望实现单次数码变焦操作，调用 [setVideoDigitalZoomControl](#RTCEngine-setvideodigitalzoomcontrol)。 - 如果你需要对摄像头进行光学变焦控制，参看 [setCameraZoomRatio](#RTCEngine-setcamerazoomratio)。 ### stopVideoDigitalZoomControl ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopVideoDigitalZoomControl() ``` > Available since 3.51 停止本地摄像头持续数码变焦。 **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 关于开始数码变焦，参看 [startVideoDigitalZoomControl](#RTCEngine-startvideodigitalzoomcontrol)。 ### registerLocalEncodedVideoFrameObserver ```java public abstract int com.ss.bytertc.engine.RTCEngine.registerLocalEncodedVideoFrameObserver(ILocalEncodedVideoFrameObserver observer) ``` 注册本地视频帧监测器。无论使用内部采集还是自定义采集，调用该方法后，SDK 每监测到一帧本地视频帧时，都会将视频帧信息通过 [onLocalEncodedVideoFrame](70081#ILocalEncodedVideoFrameObserver-onlocalencodedvideoframe) 回调给用户。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | observer | ILocalEncodedVideoFrameObserver | 本地频帧监测器，参看 [ILocalEncodedVideoFrameObserver](70081#ILocalEncodedVideoFrameObserver) 。将参数设置为 null 则取消注册。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 该方法可在进房前后的任意时间调用，在进房前调用可保证尽可能早地监测视频帧并触发回调 ### registerRemoteEncodedVideoFrameObserver ```java public abstract int com.ss.bytertc.engine.RTCEngine.registerRemoteEncodedVideoFrameObserver(IRemoteEncodedVideoFrameObserver observer) ``` 注册远端编码后视频数据回调。完成注册后，当 SDK 监测到远端编码后视频帧时，会触发 [onRemoteEncodedVideoFrame](70081#IRemoteEncodedVideoFrameObserver-onremoteencodedvideoframe) 回调 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | observer | IRemoteEncodedVideoFrameObserver | 远端编码后视频数据监测器，参看 [IRemoteEncodedVideoFrameObserver](70081#IRemoteEncodedVideoFrameObserver) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 更多自定义解码功能说明参看 [自定义视频编解码](https://www.volcengine.com/docs/6348/82921)。 - 该方法适用于手动订阅，并且进房前后均可调用，建议在进房前调用。 - 引擎销毁前需取消注册，调用该方法将参数设置为 "null" 即可。 ### setVideoSourceType ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVideoSourceType(VideoSourceType type) ``` 设置向 SDK 输入的视频源，包括屏幕流默认使用内部采集。内部采集指：使用 RTC SDK 内置的视频采集机制进行视频采集。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | VideoSourceType | 视频输入源类型，参看 [VideoSourceType](70083#VideoSourceType) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法进房前后均可调用。 - 当你已调用 [startVideoCapture](#RTCEngine-startvideocapture) 开启内部采集后，再调用此方法切换至自定义采集时，SDK 会自动关闭内部采集。 - 当你调用此方法开启自定义采集后，想要切换至内部采集，你必须先调用此方法关闭自定义采集，然后调用 [startVideoCapture](#RTCEngine-startvideocapture) 手动开启内部采集。 - 当你需要向 SDK 推送自定义编码后的视频帧，你需调用该方法将视频源切换至自定义编码视频源。 ### pushExternalVideoFrame ```java public abstract int com.ss.bytertc.engine.RTCEngine.pushExternalVideoFrame(VideoFrameData frame) ``` 推送外部视频帧。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | frame | VideoFrameData | 视频帧的数据信息 | **返回值** 方法调用结果： - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** - 该方法主动将视频帧数据用 [VideoFrameData](70083#VideoFrameData) 类封装后传递给 SDK。 - 请确保在你调用本方法前已调用 [setVideoSourceType](#RTCEngine-setvideosourcetype) 设置为自定义视频采集。 - 当使用纹理数据时，确保 [createRTCEngine](#RTCEngine-creatertcengine) 中的 `eglContext`与 `frame` 中的 `eglContext` 为 `sharedContext` 或者相同，否则会无法编码。 - 支持的格式：Raw：I420, NV12, RGBA；纹理：Texture2D, TextureOES。 ### startPushMixedStream ```java public abstract int com.ss.bytertc.engine.RTCEngine.startPushMixedStream( String taskId, MixedStreamPushTargetConfig pushTargetConfig, MixedStreamConfig mixedConfig ) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `startPushMixedStreamToCDN` 和 `startPushPublicStream` 方法用于实现下述功能。如果你已升级至 3.60 及以上版本，并且仍在使用这两个方法，请迁移到此接口。指定房间中的媒体流，合成后一路流发布到 CDN 或发布一路 WTN 流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | taskId | String | 转推直播任务 ID，长度不超过 127 字节。当 [MixedStreamConfig](70083#MixedStreamConfig) 中的 `PushTargetType = 0` 时，用于标识转推直播任务。你可以在同一房间内发起多个转推直播任务，并用不同的 ID 加以区分。当你需要发起多个转推直播任务时，应使用多个 ID；当你仅需发起一个转推直播任务时，建议使用空字符串。
当 `PushTargetType = 1` 时，为 WTN 流，此参数设置无效，传空即可。 | | pushTargetConfig | MixedStreamPushTargetConfig | 推流目标配置参数，比如设置推流地址、WTN 流 ID。参看 [MixedStreamPushTargetConfig](70083#MixedStreamPushTargetConfig)。 | | mixedConfig | MixedStreamConfig | 合流转推配置参数，比如设置合流的图片、视频视图布局和音频属性。参看 [MixedStreamConfig](70083#MixedStreamConfig)。 | **返回值** - 0：成功。你可以通过 [onMixedStreamEvent](70081#IRTCEngineEventHandler-onmixedstreamevent) 回调获取启动结果和推流过程中的事件。 - !0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 在[控制台](https://console.volcengine.com/rtc/cloudRTC?tab=callback)配置了转推直播和 WTN 流的服务端回调后，调用本接口会收到相应回调。重复调用该接口时，第二次调用会同时触发 [TranscodeStarted](https://www.volcengine.com/docs/6348/75125#transcodestarted) 和 [TranscodeUpdated](https://www.volcengine.com/docs/6348/75125#transcodeupdated)。 - 调用 [stopPushMixedStream](#RTCEngine-stoppushmixedstream) 停止转推直播。 - 调用 [updatePushMixedStream](#RTCEngine-updatepushmixedstream) 可以更新部分任务参数。 ### updatePushMixedStream ```java public abstract int com.ss.bytertc.engine.RTCEngine.updatePushMixedStream( String taskId, MixedStreamPushTargetConfig pushTargetConfig, MixedStreamConfig mixedConfig ) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `updatePushMixedStreamToCDN` 和 `updatePublicStreamParam` 方法用于实现下述功能。如果你已升级至 3.60 及以上版本，并且仍在使用这两个方法，请迁移到此接口。更新由 [startPushMixedStream](#RTCEngine-startpushmixedstream) 启动的任务参数，会收到 [onMixedStreamEvent](70081#IRTCEngineEventHandler-onmixedstreamevent) 回调。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | taskId | String | 转推直播任务 ID。指定想要更新参数设置的转推直播任务。仅当 [MixedStreamConfig](70083#MixedStreamConfig) 中的 `PushTargetType = 0` 时有效。 | | pushTargetConfig | MixedStreamPushTargetConfig | 推流目标配置参数，比如设置推流地址、WTN 流 ID。参看 [MixedStreamPushTargetConfig](70083#MixedStreamPushTargetConfig)。 | | mixedConfig | MixedStreamConfig | 转推直播配置参数，参看 [MixedStreamConfig](70083#MixedStreamConfig)。除特殊说明外，均支持过程中更新。
调用时，结构体中没有传入值的属性，会被更新为默认值。 | **返回值** - 0：成功。 - !0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### stopPushMixedStream ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopPushMixedStream( String taskId, MixedStreamPushTargetType targetType ) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `stopPushStreamToCDN` 方法来停止合流转推任务。如果你已升级至 3.60 及以上版本，并且仍在使用该方法，请迁移到此接口。停止由 [startPushMixedStream](#RTCEngine-startpushmixedstream) 启动的任务。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | taskId | String | 转推直播任务 ID。指定想要更新参数设置的转推直播任务。 | | targetType | MixedStreamPushTargetType | 参看 [MixedStreamPushTargetType](70083#MixedStreamPushTargetType)。 | **返回值** - 0：成功 - !0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### startPushSingleStream ```java public abstract int com.ss.bytertc.engine.RTCEngine.startPushSingleStream( String taskId, PushSingleStreamParam param ) ``` > Available since 3.60. 将房间内某一路音视频流，推送到指定的 RTC 房间或 CDN 地址。此过程不涉及编解码。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | taskId | String | 任务 ID。
你可以发起多个转推直播任务，并用不同的任务 ID 加以区分。当你需要发起多个转推直播任务时，应使用多个 ID；当你仅需发起一个转推直播任务时，建议使用空字符串。 | | param | PushSingleStreamParam | 转推直播配置参数。详见 [PushSingleStreamParam](70083#PushSingleStreamParam)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 在调用该接口前，你需要在[控制台](https://console.volcengine.com/rtc/cloudRTC?tab=live&from=doc)开启转推直播功能。 - 调用该方法后，关于启动结果和推流过程中的错误，会收到 [onSingleStreamEvent](70081#IRTCEngineEventHandler-onsinglestreamevent) 回调。 - 在[控制台](https://console.volcengine.com/rtc/cloudRTC?tab=callback)配置了转推直播服务端回调后，调用本接口会收到相应回调。重复调用该接口时，第二次调用会同时触发 [TranscodeStarted](https://www.volcengine.com/docs/6348/75125#transcodestarted) 和 [TranscodeUpdated](https://www.volcengine.com/docs/6348/75125#transcodeupdated)。 - 调用 [stopPushSingleStream](#RTCEngine-stoppushsinglestream) 停止任务。 - 由于本功能不进行编解码，所以推到 RTMP 的视频流会根据推流端的分辨率、编码方式、关闭摄像头等变化而变化。 ### stopPushSingleStream ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopPushSingleStream(String taskId) ``` > Available since 3.60. 自 3.60 起，该接口替代了 `stopPushStreamToCDN` 方法来停止单流转推直播任务。如果你已升级至 3.60 及以上版本，并且仍在使用该方法，请迁移到此接口。停止通过 [startPushSingleStream](#RTCEngine-startpushsinglestream) 发起的单流转推任务。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | taskId | String | 任务 ID。可以指定想要停止的单流转推直播任务。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### setVideoCaptureConfig ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVideoCaptureConfig(VideoCaptureConfig videoCaptureConfig) ``` 设置 RTC SDK 内部采集时的视频采集参数。如果你的项目使用了 SDK 内部采集模块，可以通过本接口指定视频采集参数包括模式、分辨率、帧率。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | videoCaptureConfig | VideoCaptureConfig | 视频采集参数。参看：[VideoCaptureConfig](70083#VideoCaptureConfig)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 本接口在引擎创建后即可调用，建议在调用 [startVideoCapture](#RTCEngine-startvideocapture) 前调用本接口。 - 建议同一设备上的不同引擎使用相同的视频采集参数。 - 如果调用本接口前使用内部模块开始视频采集，采集参数默认为 Auto 模式。 ### setVideoEncoderConfig ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVideoEncoderConfig(VideoEncoderConfig encoderConfig) ``` 视频发布端设置期望发布的最大分辨率视频流参数，包括分辨率、帧率、码率、网络不佳时的回退策略等（包含摄像头和屏幕的编码配置）。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | encoderConfig | VideoEncoderConfig | 期望发布的最大分辨率视频流参数。参看 [VideoEncoderConfig](70083#VideoEncoderConfig)。 | **返回值** 方法调用结果： - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 自 V3.61 版本，本接口仅设置一路视频流参数。默认状态下只有单流，如需开启多路小流请使用：[setLocalSimulcastMode](#RTCEngine-setlocalsimulcastmode)。 - 调用该方法前，SDK 默认仅发布一路视频流，分辨率为 640px × 360px \@15fps，编码偏好为帧率优先。 - 使用自定义采集时，必须调用该方法设置编码参数，以保证远端收到画面的完整性。 ### setLocalSimulcastMode ```java public abstract int com.ss.bytertc.engine.RTCEngine.setLocalSimulcastMode( VideoSimulcastMode mode, VideoEncoderConfig[] streamConfig ) ``` > Available since 3.60. 发布端进行大小流(simulcast)设置。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mode | VideoSimulcastMode | 详见 [VideoSimulcastMode](70083#VideoSimulcastMode)。默认为只发送单流。你应在进房前调用修改本参数。 | | streamConfig | VideoEncoderConfig [] | 小流参数。最多可设置 3 路。分辨率按照从小到大顺序，且每路流参数分辨率需小于大流 [setVideoEncoderConfig](#RTCEngine-setvideoencoderconfig) 设置参数。否则可能会设置失败。参看 [VideoEncoderConfig](70083#VideoEncoderConfig)。
其余模式下，默认小流参数为 160px × 90px, 码率为 50kpbs。 | **返回值** 方法调用结果： - 0：成功 - !0：失败 **注意** - 调用本方法前，SDK 默认仅发布一条分辨率为 640px × 360px \@15fps 的视频流。 - 本方法适用于摄像头采集的视频流。 - 更多信息详见[推送多路流](https://www.volcengine.com/docs/6348/70139)文档。 ### setLocalSimulcastMode ```java public abstract int com.ss.bytertc.engine.RTCEngine.setLocalSimulcastMode(VideoSimulcastMode mode) ``` > Available since 3.60. 发布端开启大小流(simulcast)功能。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mode | VideoSimulcastMode | 详见 [VideoSimulcastMode](70083#VideoSimulcastMode)。默认为只发送单流。
其余模式下，默认小流参数为 160px × 90px, 码率为 50kpbs。 | **返回值** 方法调用结果： - 0：成功 - !0：失败 **注意** - 你应在进房前调用本接口。 - 调用该方法前，SDK 默认仅发布一条分辨率为 640px × 360px，帧率为 15fps 的视频流。 - 如需自定义小流参数请查看它的重载方法 setLocalSimulcastMode(VideoSimulcastMode mode, VideoEncoderConfig[] streamConfig)。 - 该方法适用于摄像头采集的视频流。 - 更多信息详见[推送多路流](https://www.volcengine.com/docs/6348/70139)文档。 ### setAudioSourceType ```java public abstract int com.ss.bytertc.engine.RTCEngine.setAudioSourceType(AudioSourceType type) ``` 切换音频采集方式 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | AudioSourceType | 音频数据源，详见 [AudioSourceType](70083#AudioSourceType)。
默认使用内部音频采集。音频采集和渲染方式无需对应。 | **返回值** 方法调用结果： - =0：切换成功。 - < 0：切换失败。 **注意** - 进房前后调用此方法均有效。 - 如果你调用此方法由内部采集切换至自定义采集，SDK 会自动关闭内部采集。然后，调用 [pushExternalAudioFrame](#RTCEngine-pushexternalaudioframe) 推送自定义采集的音频数据到 RTC SDK 用于传输。 - 如果你调用此方法由自定义采集切换至内部采集，你必须再调用 [startAudioCapture](#RTCEngine-startaudiocapture) 手动开启内部采集。 ### setAudioRenderType ```java public abstract int com.ss.bytertc.engine.RTCEngine.setAudioRenderType(AudioRenderType type) ``` 切换音频渲染方式 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | AudioRenderType | 音频输出类型，详见 [AudioRenderType](70083#AudioRenderType)
默认使用内部音频渲染。音频采集和渲染方式无需对应。 | **返回值** 方法调用结果： - =0：切换成功。 - < 0：切换失败。 **注意** - 进房前后调用此方法均有效。 - 如果你调用此方法切换至自定义渲染，调用 [pullExternalAudioFrame](#RTCEngine-pullexternalaudioframe) 获取音频数据。 ### pushExternalAudioFrame ```java public abstract int com.ss.bytertc.engine.RTCEngine.pushExternalAudioFrame(AudioFrame audioFrame) ``` 推送自定义采集的音频数据到 RTC SDK。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audioFrame | AudioFrame | 音频数据帧，详见 [AudioFrame](70083#AudioFrame)

音频采样格式必须为 S16。音频缓冲区内的数据格式必须为 PCM，其容量大小应该为 audioFrame.samples × audioFrame.channel × 2。
必须指定具体的采样率和声道数，不支持设置为自动。

| **返回值** 方法调用结果 - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 推送自定义采集的音频数据前，必须先调用 [setAudioSourceType](#RTCEngine-setaudiosourcetype) 开启自定义采集。 - 你必须每隔 10 毫秒推送一次外部采集的音频数据。单次推送的 samples (音频采样点个数）应该为 audioFrame.sampleRate / 100。比如设置采样率为 48000 时，每次应该推送 480 个采样点。 ### pullExternalAudioFrame ```java public abstract int com.ss.bytertc.engine.RTCEngine.pullExternalAudioFrame(AudioFrame audioFrame) ``` 拉取下行音频数据用于自定义音频渲染。调用该方法后，SDK 会主动拉取待播放的音频数据，包括远端已解码和混音后的音频数据，用于外部播放。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audioFrame | AudioFrame | 音频数据帧，详见 [AudioFrame](70083#AudioFrame) | **返回值** 方法调用结果 - 0：设置成功 - < 0：设置失败 **注意** - 拉取外部音频数据前，必须先调用 [setAudioRenderType](#RTCEngine-setaudiorendertype) 启用自定义音频渲染。 - 由于 RTC SDK 的帧长为 10 毫秒，你应当每隔 10 毫秒拉取一次音频数据。确保音频采样点数（sample）x 拉取频率等于 audioFrame 的采样率（sampleRate）。如设置采样率为 48000 时，每 10 毫秒调用本接口拉取数据，每次应拉取 480 个采样点。 - 音频采样格式为 S16。音频缓冲区内的数据格式为 PCM 数据，其容量大小为 audioFrame.samples × audioFrame.channel × 2。 ### pushReferenceAudioPCMData ```java public abstract int com.ss.bytertc.engine.RTCEngine.pushReferenceAudioPCMData(AudioFrame audioFrame) ``` 向 SDK 发送由自定义处理后的 PCM 音频数据，作为回声消除的参考信号 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audioFrame | AudioFrame | 音频数据帧，详见 [AudioFrame](70083#AudioFrame) | **返回值** 方法调用结果 + 0：方法调用成功 + <-1：方法调用失败 **注意** + 由于 RTC SDK 的帧长为 10 毫秒，你应当每隔 10 毫秒发送一次音频数据。确保音频采样点数（sample）x 发送频率等于 audioFrame 的采样率（sampleRate）。如设置采样率为 48000 时，每 10 毫秒调用本接口发送数据，每次应发送 480 个采样点。 + 音频采样格式为 S16。音频缓冲区内的数据格式为 PCM 数据，其容量大小为 audioFrame.samples × audioFrame.channel × 2。 ### createRTCRoom ```java public abstract RTCRoom com.ss.bytertc.engine.RTCEngine.createRTCRoom(String roomId) ``` 创建 RTC 房间实例。调用此方法仅返回一个房间实例，你仍需调用 [joinRoom](#RTCRoom-joinroom) 才能真正地创建/加入房间。多次调用此方法以创建多个 [RTCRoom](#RTCRoom) 实例。分别调用各 RTCRoom 实例中的 [joinRoom](#RTCRoom-joinroom) 方法，同时加入多个房间。多房间模式下，用户可以同时订阅各房间的音视频流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | roomId | String | 标识通话房间的房间 ID。该字符串符合正则表达式：`[a-zA-Z0-9_\@\\-\\.]{1,128}`。 | **返回值** 创建的 [RTCRoom](#RTCRoom) 房间实例。返回 NULL 时，请确认指定房间是否已经存在或 roomId 格式错误。 **注意** - 如果需要加入的房间已存在，你仍需先调用本方法来获取 RTCRoom 实例，再调用 [joinRoom](#RTCRoom-joinroom) 加入房间。 - 请勿使用同样的 roomId 创建多个房间，否则后创建的房间实例会替换先创建的房间实例。 - 如果你需要在多个房间发布音视频流，无须创建多房间，直接调用 [startForwardStreamToRooms](#RTCRoom-startforwardstreamtorooms) 开始跨房间转发媒体流。 ### createGameRoom ```java public abstract IGameRoom com.ss.bytertc.engine.RTCEngine.createGameRoom( String roomId, GameRoomConfig config ) ``` 创建游戏语音房间实例。调用此方法仅返回一个房间实例，你仍需调用 [joinRoom](#IGameRoom-joinroom) 才能真正地创建/加入房间。多次调用此方法以创建多个 [IGameRoom](#IGameRoom) 实例。分别调用各 RTCRoom 实例中的 [joinRoom](#IGameRoom-joinroom) 方法，同时加入多个房间。多房间模式下，用户可以同时订阅各房间的音视频流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | roomId | String | 标识通话房间的房间 ID。该字符串符合正则表达式：`[a-zA-Z0-9_\@\\-\\.]{1,128}`。 | | config | GameRoomConfig | 游戏语音房间配置。参看 [GameRoomConfig](70083#GameRoomConfig)。 | **返回值** 创建的 [IGameRoom](#IGameRoom) 房间实例。返回 NULL 时，请确认指定房间是否已经存在或 roomId 格式错误。 **注意** - 如果需要加入的房间已存在，你仍需先调用本方法来获取 IGameRoom实例，再调用 [joinRoom](#IGameRoom-joinroom) 加入房间。 - 请勿使用同样的 roomId 创建多个房间，否则后创建的房间实例会替换先创建的房间实例。 - 如果你需要在多个房间发布音视频流，无须创建多房间，直接调用 [startForwardStreamToRooms](#RTCRoom-startforwardstreamtorooms) 开始跨房间转发媒体流。 ### createRTSRoom ```java public abstract RTSRoom com.ss.bytertc.engine.RTCEngine.createRTSRoom(String roomId) ``` 创建 [RTSRoom](#RTSRoom) 实例。调用此方法仅返回一个房间实例，你仍需调用 [joinRTSRoom](#RTSRoom-joinrtsroom) 才能真正地创建/加入房间。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | roomId | String | 标识通话房间的房间 ID。该字符串符合正则表达式：`[a-zA-Z0-9_\@\\-\\.]{1,128}`。 | **返回值** 创建的 [RTSRoom](#RTSRoom) 房间实例。 **注意** 请勿使用同样的 roomId 创建多个房间，否则后创建的房间实例会替换先创建的房间实例。 ### setPublishFallbackOption ```java public abstract int com.ss.bytertc.engine.RTCEngine.setPublishFallbackOption(PublishFallbackOption option) ``` 设置发布的音视频流的回退选项。你可以调用该接口设置网络不佳或设备性能不足时从大流起进行降级处理，以保证通话质量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | option | PublishFallbackOption | 本地发布的音视频流回退选项，参看 [PublishFallbackOption](70083#PublishFallbackOption)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法仅在调用 [setLocalSimulcastMode](#RTCEngine-setlocalsimulcastmode-2) 开启了发送多路视频流的情况下生效。 - 该方法必须在进房前设置，进房后设置或更改设置无效。 - 调用该方法后，如因性能或网络不佳产生发布性能回退或恢复，本端会提前收到 [onPerformanceAlarms](70081#IRTCEngineEventHandler-onperformancealarms) 回调发出的告警，以便采集设备配合调整。 - 设置回退后，本地发布的音视频流发生回退或从回退中恢复时，远端会收到 [onSimulcastSubscribeFallback](70081#IRTCEngineEventHandler-onsimulcastsubscribefallback) 回调，通知该情况。 - 你可以调用客户端 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。 ### setSubscribeFallbackOption ```java public abstract int com.ss.bytertc.engine.RTCEngine.setSubscribeFallbackOption(SubscribeFallbackOptions option) ``` 设置订阅的音视频流的回退选项。你可调用该接口设置网络不佳或设备性能不足时允许订阅流进行降级或只订阅音频流，以保证通话流畅。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | option | SubscribeFallbackOptions | 订阅的音视频流回退选项，参看 [SubscribeFallbackOptions](70083#SubscribeFallbackOptions)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 你必须在进房前设置，进房后设置或更改设置无效。 - 设置回退选项后，订阅的音视频流发生回退或从回退中恢复时，会收到 [onSimulcastSubscribeFallback](70081#IRTCEngineEventHandler-onsimulcastsubscribefallback) 和 [onRemoteVideoSizeChanged](70081#IRTCEngineEventHandler-onremotevideosizechanged) 回调通知。 - 你可以调用 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。 ### setRemoteUserPriority ```java public abstract int com.ss.bytertc.engine.RTCEngine.setRemoteUserPriority( String roomid, String uid, RemoteUserPriority priority ) ``` 设置用户优先级。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | roomid | String | 房间 ID | | uid | String | 远端用户的 ID 。 | | priority | RemoteUserPriority | 远端用户的优先级，详见枚举类型 [RemoteUserPriority](70083#RemoteUserPriority) 。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法与 [setSubscribeFallbackOption](#RTCEngine-setsubscribefallbackoption) 搭配使用。 - 如果开启了订阅流回退选项，弱网或性能不足时会优先保证收到的高优先级用户的流的质量。 - 该方法在进房前后都可以使用，可以修改远端用户的优先级。 ### setBusinessId ```java public abstract int com.ss.bytertc.engine.RTCEngine.setBusinessId(String businessId) ``` 设置业务标识参数可通过 businessId 区分不同的业务场景。businessId 由客户自定义，相当于一个“标签”，可以分担和细化现在 AppId 的逻辑划分的功能，但不需要鉴权。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | businessId | String | 用户设置的自己的 businessId 值
businessId 只是一个标签，颗粒度需要用户自定义。 | **返回值** - 0：成功。 - -2：输入非法，合法字符包括所有小写字母、大写字母和数字，除此外还包括四个独立字符，分别是：英文句号，短横线，下划线和 \@ 。 **注意** - 需要在进房前调用，进房后调用该方法无效。 ### setEncryptInfo ```java public abstract int com.ss.bytertc.engine.RTCEngine.setEncryptInfo( int aesType, String key ) ``` 设置传输时使用内置加密的方式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | aesType | int | 加密类型。可选参数为 0、1、2、3、4。代表的含义如下：

不加密
AES-128-CBC
AES-256-CBC
AES-128-ECB
AES-256-ECB

| | key | String | 加密密钥。长度限制为 36 位，超出部分将会被截断。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法与 [setCustomizeEncryptHandler](#RTCEngine-setcustomizeencrypthandler) 为互斥关系，即按照调用顺序，最后一个调用的方法为最终生效的版本。 - 该方法必须在调用 [joinRoom](#RTCRoom-joinroom) 之前调用，可重复调用，以最后调用的参数作为生效参数 ### setCustomizeEncryptHandler ```java public abstract int com.ss.bytertc.engine.RTCEngine.setCustomizeEncryptHandler(RTCEncryptHandler handler) ``` 设置自定义加密和解密方式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | handler | RTCEncryptHandler | 自定义加密 handler，需要实现里面的加密和解密方法。参看 [IRTCEncryptionHandler](70081#IRTCEncryptionHandler)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法与 [setEncryptInfo](#RTCEngine-setencryptinfo) 为互斥关系，即按照调用顺序，最后一个调用的方法为最终生效的版本 - 该方法必须在进房前调用，可重复调用，以最后调用的参数作为生效参数 - 无论加密或者解密，其对原始数据的长度修改，需要控制在 180\% 之间，即如果输入数据为 100 字节，则处理完成后的数据必须不超过 180 字节，如果加密或解密结果超出该长度限制，则该音视频帧可能会被丢弃。 - 数据加密/解密为串行执行，因而视实现方式不同，可能会影响到最终渲染效率，是否使用该方法，需要由使用方谨慎评估 ### getVideoEffectInterface ```java public abstract IVideoEffect com.ss.bytertc.engine.RTCEngine.getVideoEffectInterface() ``` 获取视频特效接口。 **返回值** 视频特效接口，参看 [IVideoEffect](#IVideoEffect)。 ### enableEffectBeauty ```java public abstract int com.ss.bytertc.engine.RTCEngine.enableEffectBeauty(boolean enable) ``` 开启/关闭基础美颜。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 基础美颜开关

true：开启基础美颜
false：关闭基础美颜（默认）

| **返回值** - 0：调用成功。 - –1001：RTC SDK 版本不支持此功能。 - -12：本方法不支持在 Audio SDK 中使用。 - < 0：调用失败，特效 SDK 内部错误，具体错误码请参考[错误码表](https://www.volcengine.com/docs/6705/102042)。 **注意** - 本方法不能与高级视频特效接口共用。如已购买高级视频特效，建议参看[集成指南](https://www.volcengine.com/docs/6348/114717)使用高级美颜、特效、贴纸功能等。 - 使用此功能需要集成特效 SDK，建议使用特效 SDK v4.4.2+ 版本。更多信息参看 [Native 端基础美颜](https://www.volcengine.com/docs/6348/372605)。 - 调用 [setBeautyIntensity](#RTCEngine-setbeautyintensity) 设置基础美颜强度。若在调用本方法前没有设置美颜强度，则使用默认强度。各基础美颜模式的强度默认值分别为：美白 0.7，磨皮 0.8，锐化 0.5，清晰 0.7。 - 本方法仅适用于视频源，不适用于屏幕源。 ### setBeautyIntensity ```java public abstract int com.ss.bytertc.engine.RTCEngine.setBeautyIntensity( EffectBeautyMode beautyMode, float intensity ) ``` 调整基础美颜强度 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | beautyMode | EffectBeautyMode | 基础美颜模式，参看 [EffectBeautyMode](70083#EffectBeautyMode)。 | | intensity | float | 美颜强度，取值范围为 [0,1]。强度为 0 表示关闭。
各基础美颜模式的强度默认值分别为：美白 0.7，磨皮 0.8，锐化 0.5，清晰 0.7。 | **返回值** - 0：调用成功。 - –2：`intensity` 范围超限。 - –1001：RTC SDK 版本不支持此功能。 - < 0：调用失败，特效 SDK 内部错误，具体错误码请参考[错误码表](https://www.volcengine.com/docs/6705/102042)。 **注意** - 若在调用 [enableEffectBeauty](#RTCEngine-enableeffectbeauty) 前设置美颜强度，则对应美颜功能的强度初始值会根据设置更新。 - 销毁引擎后，美颜功能强度恢复默认值。 ### setVideoOrientation ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVideoOrientation(VideoOrientation orientation) ``` 在自定义视频前处理及编码前，设置 RTC 链路中的视频帧朝向，默认为 Adaptive 模式。移动端开启视频特效贴纸，或使用自定义视频前处理时，建议固定视频帧朝向为 Portrait 模式。单流转推场景下，建议根据业务需要固定视频帧朝向为 Portrait 或 Landscape 模式。不同模式的具体显示效果参看[视频帧朝向](https://www.volcengine.com/docs/6348/128787)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | orientation | VideoOrientation | 视频帧朝向，参看 [VideoOrientation](70083#VideoOrientation)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 视频帧朝向设置仅适用于内部采集视频源。对于自定义采集视频源，设置视频帧朝向可能会导致错误，例如宽高对调。屏幕源不支持设置视频帧朝向。 - 编码分辨率的更新与视频帧处理是异步操作，进房后切换视频帧朝向可能导致画面出现短暂的裁切异常，因此建议在进房前设置视频帧朝向，且不在进房后进行切换。 ### setRuntimeParameters ```java public abstract int com.ss.bytertc.engine.RTCEngine.setRuntimeParameters(JSONObject params) ``` 设置运行时的参数 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | params | JSONObject | 保留参数 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 该接口需在 [joinRoom](#RTCRoom-joinroom) 和 [startAudioCapture](#RTCEngine-startaudiocapture) 之前调用。 ### feedback ```java public abstract int com.ss.bytertc.engine.RTCEngine.feedback( List types, ProblemFeedbackInfo info ) ``` 将用户反馈的问题上报到 RTC。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | types | List\ | 预设问题列表，参看 [ProblemFeedbackOption](70083#ProblemFeedbackOption) | | info | ProblemFeedbackInfo | 预设问题以外的其他问题的具体描述、房间信息，参看 [ProblemFeedbackInfo](70083#ProblemFeedbackInfo) | **返回值** - 0：成功。 - -3：失败。 **注意** - 你可以在 [RTC 控制台](https://console.volcengine.com/rtc/callQualityRTC/feedback)上查看用户通过此接口提交的反馈详情和整体趋势。 - 如果用户上报时在房间内，那么问题会定位到用户当前所在的一个或多个房间；如果用户上报时不在房间内，那么问题会定位到引擎此前退出的房间。 ### getNativeHandle ```java public abstract long com.ss.bytertc.engine.RTCEngine.getNativeHandle() ``` > Available since 353 since 353 获取 C++ 层 [IRTCEngine 句柄](https://www.volcengine.com/docs/6348/70095#irtcengine)。 **返回值** - \>0：方法调用成功, 返回 C++ 层 `IRTCEngine` 的地址。 - -1：方法调用失败 **注意** 在一些场景下，获取 C++ 层 `IRTCEngine`，并通过其完成操作，相较于通过 Java 封装层完成有显著更高的执行效率。典型的场景有：视频/音频帧自定义处理，音视频通话加密等。 ### startAudioRecording ```java public abstract int com.ss.bytertc.engine.RTCEngine.startAudioRecording(AudioRecordingConfig config) ``` 开始音频录制，并生成录音文件保存到本地。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | config | AudioRecordingConfig | 参看 [AudioRecordingConfig](70083#AudioRecordingConfig) | **返回值** - 0：正常 - -2：参数设置异常 - -3：当前版本 SDK 不支持该特性，请联系技术支持人员 **注意** - 调用该方法后，会立即启动录制任务并创建录音文件。 - 录制包含各种音频效果。但不包含背景音乐。 - 录制本地麦克风的音频时，请确保已调用 [startAudioCapture](#RTCEngine-startaudiocapture) 接口打开麦克风采集。 - 调用 [stopAudioRecording](#RTCEngine-stopaudiorecording) 关闭录制。 - 加入房间前后均可调用。在进房前调用该方法，退房之后，录制任务不会自动停止，需调用 [stopAudioRecording](#RTCEngine-stopaudiorecording) 关闭录制。在进房后调用该方法，退房之后，录制任务会自动被停止。如果加入了多个房间，录制的文件中会包含各个房间的音频。 - 调用该方法后，你会收到 [onAudioRecordingStateUpdate](70081#IRTCEngineEventHandler-onaudiorecordingstateupdate) 回调。 ### stopAudioRecording ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopAudioRecording() ``` 停止音频文件录制 **返回值** - 0：正常 - -3：当前版本 SDK 不支持该特性，请联系技术支持人员 **注意** 调用 [startAudioRecording](#RTCEngine-startaudiorecording) 开启本地录制后，你必须调用该方法停止录制。 ### getAudioEffectPlayer ```java public abstract IAudioEffectPlayer com.ss.bytertc.engine.RTCEngine.getAudioEffectPlayer() ``` > Available since 3.53 创建音效播放器实例。 **返回值** 音效播放器。详见 [IAudioEffectPlayer](#IAudioEffectPlayer)。 ### getMediaPlayer ```java public abstract IMediaPlayer com.ss.bytertc.engine.RTCEngine.getMediaPlayer(int playerId) ``` > Available since 3.53 创建音乐播放器实例。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | playerId | int | 音乐播放器实例 id。取值范围为 `[0, 3]`。最多同时存在 4 个实例，超出取值范围时返回 nullptr。 | **返回值** 音乐播放器实例，详见 [IMediaPlayer](#IMediaPlayer) ### setScreenAudioSourceType ```java public abstract int com.ss.bytertc.engine.RTCEngine.setScreenAudioSourceType(AudioSourceType sourceType) ``` 在屏幕共享时，设置屏幕音频的采集方式（内部采集/自定义采集） **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | sourceType | AudioSourceType | 屏幕音频输入源类型, 参看 [AudioSourceType](70083#AudioSourceType)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 默认采集方式是 RTC SDK 内部采集。 - 如果设定为内部采集，你必须再调用 startScreenCapture 开始采集。开启后，可以再次本接口切换为外部采集，此时内部采集将自动停止。 - 如果设定为自定义采集，你必须再调用 [pushScreenAudioFrame](#RTCEngine-pushscreenaudioframe) 将自定义采集到的屏幕音频帧推送到 RTC SDK。 ### pushScreenAudioFrame ```java public abstract int com.ss.bytertc.engine.RTCEngine.pushScreenAudioFrame(AudioFrame audioFrame) ``` 使用自定义采集方式，采集屏幕共享时的屏幕音频时，将音频帧推送至 RTC SDK 处进行编码等处理。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audioFrame | AudioFrame | 音频数据帧，参见 [AudioFrame](70083#AudioFrame)

音频采样格式为 S16。音频缓冲区内的数据格式必须为 PCM 数据，其容量大小应该为 samples × frame.channel × 2。
必须指定具体的采样率和声道数，不支持设置为自动。

| **返回值** 方法调用结果 - 0：设置成功。 - < 0：设置失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用此接口推送屏幕共享时的自定义采集的音频数据前，必须调用 [setScreenAudioSourceType](#RTCEngine-setscreenaudiosourcetype) 开启屏幕音频自定义采集。 - 你应每隔 10 毫秒，调用一次此方法推送一次自定义采集的音频帧。一次推送的音频帧中应包含 frame.sample_rate / 100 个音频采样点。比如，假如采样率为 48000Hz，则每次应该推送 480 个采样点。 - 调用此接口将自定义采集的音频帧推送到 RTC SDK 后，你必须调用 publishScreenAudio 将采集到的屏幕音频推送到远端。在调用 publishScreenAudio 前，推送到 RTC SDK 的音频帧信息会丢失。 ### setExternalVideoEncoderEventHandler ```java public abstract int com.ss.bytertc.engine.RTCEngine.setExternalVideoEncoderEventHandler(IExternalVideoEncoderEventHandler handler) ``` 注册自定义编码帧推送事件回调 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | handler | IExternalVideoEncoderEventHandler | 自定义编码帧回调类，参看 [IExternalVideoEncoderEventHandler](70081#IExternalVideoEncoderEventHandler) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法需在进房前调用。 - 引擎销毁前需取消注册，调用该方法将参数设置为 "null" 即可。 ### setEarMonitorMode ```java public abstract int com.ss.bytertc.engine.RTCEngine.setEarMonitorMode(EarMonitorMode mode) ``` 开启/关闭耳返功能。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mode | EarMonitorMode | 是否开启耳返功能，参看 [EarMonitorMode](70083#EarMonitorMode)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 耳返功能仅适用于由 RTC SDK 内部采集的音频。 - 使用耳返功能必须佩戴耳机。为保证低延时耳返最佳体验，建议佩戴有线耳机。蓝牙耳机不支持硬件耳返。 - RTC SDK 支持硬件耳返和软件耳返。一般来说，硬件耳返延时低且音质好。如果 App 在手机厂商的硬件耳返白名单内，且运行环境存在支持硬件耳返的 SDK，RTC SDK 默认启用硬件耳返。使用华为手机硬件耳返功能时，请添加[华为硬件耳返的依赖配置](https://www.volcengine.com/docs/6348/1155036)。 ### setEarMonitorMode ```java public abstract int com.ss.bytertc.engine.RTCEngine.setEarMonitorMode( EarMonitorMode mode, int filter ) ``` > Available since 3.60. 开启/关闭耳返功能，并控制是否对耳返音频应用本地音频处理。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mode | EarMonitorMode | 是否开启耳返功能，参看 [EarMonitorMode](70083#EarMonitorMode)。默认关闭。 | | filter | int | 是否对耳返音频应用本地音频处理，参看 [EarMonitorAudioFilter](70083#EarMonitorAudioFilter)。默认不经过音频处理。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 耳返功能仅适用于由 RTC SDK 内部采集的音频。 - 使用耳返功能必须佩戴耳机。为保证低延时耳返最佳体验，建议佩戴有线耳机。蓝牙耳机不支持硬件耳返。 - RTC SDK 支持硬件耳返和软件耳返。一般来说，硬件耳返延时低且音质好。如果 App 在手机厂商的硬件耳返白名单内，且运行环境存在支持硬件耳返的 SDK，RTC SDK 默认启用硬件耳返。使用华为手机硬件耳返功能时，请添加[华为硬件耳返的依赖配置](https://www.volcengine.com/docs/6348/1155036)。 ### setEarMonitorVolume ```java public abstract int com.ss.bytertc.engine.RTCEngine.setEarMonitorVolume(int volume) ``` 设置耳返音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 耳返音量，调节范围：[0,100]，单位：\% | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 设置耳返音量前，你必须先调用 [setEarMonitorMode](#RTCEngine-setearmonitormode) 打开耳返功能。 ### enableAudioPropertiesReport ```java public abstract int com.ss.bytertc.engine.RTCEngine.enableAudioPropertiesReport(AudioPropertiesConfig config) ``` 启用音频信息提示。开启提示后，你可以收到 [onLocalAudioPropertiesReport](70081#IRTCEngineEventHandler-onlocalaudiopropertiesreport)，[onRemoteAudioPropertiesReport](70081#IRTCEngineEventHandler-onremoteaudiopropertiesreport) 和 [onActiveSpeaker](70081#IRTCEngineEventHandler-onactivespeaker)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | config | AudioPropertiesConfig | 详见 [AudioPropertiesConfig](70083#AudioPropertiesConfig) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### sendStreamSyncInfo ```java public abstract int com.ss.bytertc.engine.RTCEngine.sendStreamSyncInfo( byte[] data, StreamSyncInfoConfig config ) ``` 发送音频流同步信息。将消息通过音频流发送到远端，并实现与音频流同步，该接口调用成功后，远端用户会收到 [onStreamSyncInfoReceived](70081#IRTCEngineEventHandler-onstreamsyncinforeceived) 回调。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | data | byte[] | 消息内容。 | | config | StreamSyncInfoConfig | 音频流同步信息的相关配置。详见 [StreamSyncInfoConfig](70083#StreamSyncInfoConfig) 。 | **返回值** - \>=0：消息发送成功。返回成功发送的次数。 - -1：消息发送失败。消息长度大于 255 字节。 - -2：消息发送失败。传入的消息内容为空。 - -3：消息发送失败。通过屏幕流进行消息同步时，此屏幕流还未发布。 - -4：消息发送失败。通过用麦克风或自定义设备采集到的音频流进行消息同步时，此音频流还未发布，详见错误码 [ErrorCode](70082#ErrorCode)。 **注意** - 调用本接口的频率建议不超过 50 次每秒。 - 在 `CHANNEL_PROFILE_INTERACTIVE_PODCAST` 房间模式下，此消息一定会送达。在其他房间模式下，如果本地用户未说话，此消息不一定会送达。 ### isCameraTorchSupported ```java public abstract boolean com.ss.bytertc.engine.RTCEngine.isCameraTorchSupported() ``` 检测当前使用的摄像头（前置/后置），是否支持闪光灯。 **返回值** - true：支持 - false：不支持 **注意** 必须已调用 [startVideoCapture](#RTCEngine-startvideocapture) 使用 SDK 内部采集模块进行视频采集时，才能检测闪光能力。 ### isCameraZoomSupported ```java public abstract boolean com.ss.bytertc.engine.RTCEngine.isCameraZoomSupported() ``` 检测当前使用的摄像头（前置/后置），是否支持变焦（数码/光学变焦）。 **返回值** - true：支持 - false：不支持 **注意** 必须已调用 [startVideoCapture](#RTCEngine-startvideocapture) 使用 SDK 内部采集模块进行视频采集时，才能检测摄像头变焦能力。 ### setCameraZoomRatio ```java public abstract int com.ss.bytertc.engine.RTCEngine.setCameraZoomRatio(float zoom) ``` 设置当前使用的摄像头（前置/后置）的光学变焦倍数 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | zoom | float | 变焦倍数。取值范围是 [1, <最大变焦倍数>]。
最大变焦倍数可以通过调用 [getCameraZoomMaxRatio](#RTCEngine-getcamerazoommaxratio) 获取。 | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 必须已调用 [startVideoCapture](#RTCEngine-startvideocapture) 使用 SDK 内部采集模块进行视频采集时，才能设置摄像头变焦倍数。 - 设置结果在调用 [stopVideoCapture](#RTCEngine-stopvideocapture) 关闭内部采集后失效。 - 你可以调用 [setVideoDigitalZoomConfig](#RTCEngine-setvideodigitalzoomconfig) 设置数码变焦参数，调用 [setVideoDigitalZoomControl](#RTCEngine-setvideodigitalzoomcontrol) 进行数码变焦。 ### getCameraZoomMaxRatio ```java public abstract float com.ss.bytertc.engine.RTCEngine.getCameraZoomMaxRatio() ``` 获取当前使用的摄像头（前置/后置）的最大变焦倍数 **返回值** 最大变焦倍数 **注意** 必须已调用 [startVideoCapture](#RTCEngine-startvideocapture) 使用 SDK 内部采集模块进行视频采集时，才能检测摄像头最大变焦倍数。 ### setCameraTorch ```java public abstract int com.ss.bytertc.engine.RTCEngine.setCameraTorch(TorchState torchState) ``` 打开/关闭当前使用的摄像头（前置/后置）的闪光灯 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | torchState | TorchState | 闪光灯状态。参考 [TorchState](70083#TorchState) | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 必须已调用 [startVideoCapture](#RTCEngine-startvideocapture) 使用 SDK 内部采集模块进行视频采集时，才能设置闪光灯。 - 设置结果在调用 [stopVideoCapture](#RTCEngine-stopvideocapture) 关闭内部采集后失效。 ### isCameraFocusPositionSupported ```java public abstract boolean com.ss.bytertc.engine.RTCEngine.isCameraFocusPositionSupported() ``` 检查当前使用的摄像头是否支持手动对焦。 **返回值** - true：支持。 - false：不支持。 **注意** 必须已调用 [startVideoCapture](#RTCEngine-startvideocapture) 使用 SDK 内部采集模块进行视频采集，才能检查摄像头是否支持手动对焦。 ### setCameraFocusPosition ```java public abstract int com.ss.bytertc.engine.RTCEngine.setCameraFocusPosition( float x, float y ) ``` 设置当前使用的摄像头的对焦点。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | x | float | 对焦点水平方向归一化坐标。以本地预览画布的左上为原点，取值范围为 [0, 1]，0 表示最左边，1 表示最右边。 | | y | float | 对焦点垂直方向归一化坐标。以本地预览画布的左上为原点，取值范围为 [0, 1]，0 表示最上边，1 表示最下边。 | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 必须已调用 [startVideoCapture](#RTCEngine-startvideocapture) 使用 SDK 内部采集模块进行视频采集，并且使用 SDK 内部渲染时，才能设置对焦点。 - 移动设备时，自动取消对焦点设置。 - 调用 [stopVideoCapture](#RTCEngine-stopvideocapture) 关闭内部采集后，设置的对焦点失效。 ### isCameraExposurePositionSupported ```java public abstract boolean com.ss.bytertc.engine.RTCEngine.isCameraExposurePositionSupported() ``` 检查当前使用的摄像头是否支持手动设置曝光点。 **返回值** - true：支持。 - false：不支持。 **注意** 必须已调用 [startVideoCapture](#RTCEngine-startvideocapture) 使用 SDK 内部采集模块进行视频采集时，才能检查曝光点设置能力。 ### setCameraExposurePosition ```java public abstract int com.ss.bytertc.engine.RTCEngine.setCameraExposurePosition( float x, float y ) ``` 设置当前使用的摄像头的曝光点 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | x | float | 曝光点水平方向归一化坐标。以本地预览画布的左上为原点，取值范围为 [0, 1]，0 表示最左边，1 表示最右边。 | | y | float | 曝光点垂直方向归一化坐标。以本地预览画布的左上为原点，取值范围为 [0, 1]，0 表示最上边，1 表示最下边。 | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 必须已调用 [startVideoCapture](#RTCEngine-startvideocapture) 使用 SDK 内部采集模块进行视频采集，并且使用 SDK 内部渲染时，才能设置曝光点。 - 移动设备时，自动取消曝光点设置。 - 调用 [stopVideoCapture](#RTCEngine-stopvideocapture) 关闭内部采集后，设置的曝光点失效。 ### setCameraExposureCompensation ```java public abstract int com.ss.bytertc.engine.RTCEngine.setCameraExposureCompensation(float val) ``` 设置当前使用的摄像头的曝光补偿。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | val | float | 曝光补偿值，取值范围 [-1, 1]，0 为系统默认值(没有曝光补偿)。 | **返回值** - 0：成功。 - < 0：失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 必须已调用 [startVideoCapture](#RTCEngine-startvideocapture) 使用 SDK 内部采集模块进行视频采集时，才能设置曝光补偿。 - 调用 [stopVideoCapture](#RTCEngine-stopvideocapture) 关闭内部采集后，设置的曝光补偿失效。 ### enableCameraAutoExposureFaceMode ```java public abstract int com.ss.bytertc.engine.RTCEngine.enableCameraAutoExposureFaceMode(boolean enable) ``` > Available since 353 启用或禁用内部采集时人脸自动曝光模式。此模式会改善强逆光下，脸部过暗的问题；但也会导致 ROI 以外区域过亮/过暗的问题。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | boolean | 是否启用。iOS默认开启，Android默认关闭。 | **返回值** - 0：成功。 - < 0：失败。 **注意** 你必须在调用 [startVideoCapture](#RTCEngine-startvideocapture) 开启内部采集前，调用此接口方可生效。 ### setCameraAdaptiveMinimumFrameRate ```java public abstract int com.ss.bytertc.engine.RTCEngine.setCameraAdaptiveMinimumFrameRate(int framerate) ``` > Available since 353 设置内部采集适用动态帧率时，帧率的最小值。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | framerate | int | 最小值。单位为 fps。默认值是 7。
动态帧率的最大帧率是通过 [setVideoCaptureConfig](#RTCEngine-setvideocaptureconfig) 设置的帧率值。当传入参数大于最大帧率时，使用固定帧率模式，帧率为最大帧率；当传入参数小于最大帧率时，使用动态帧率。 | **返回值** - 0：成功。 - !0：失败。 **注意** - 你必须在调用 [startVideoCapture](#RTCEngine-startvideocapture) 开启内部采集前，调用此接口方可生效。 - 如果由于性能降级、静态适配等原因导致采集最大帧率变化时，已设置的最小帧率值会与新的采集最大帧率值重新比较。比较结果变化可能导致固定/动态帧率模式切换。 - 对 Android，默认开启动态帧率模式 - 对 iOS，默认使用固定帧率模式 ### enableAlphaChannelVideoEncode ```java public abstract int com.ss.bytertc.engine.RTCEngine.enableAlphaChannelVideoEncode(AlphaLayout alphaLayout) ``` > Available since 3.58 开启自定义采集视频帧的 Alpha 通道编码功能。适用于需要分离推流端视频主体与背景，且在拉流端可自定义渲染背景的场景。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | alphaLayout | AlphaLayout | 分离后的 Alpha 通道相对于 RGB 通道信息的排列位置。当前仅支持 AlphaLayout.TOP，即置于 RGB 通道信息上方。 | **返回值** 方法调用结果： - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该接口仅作用于自定义采集的、并且使用 RGBA 色彩模型的视频帧，包括 VideoPixelFormat.TEXTURE_2D、VideoPixelFormat.TEXTURE_OES、VideoPixelFormat.RGBA。 - 该接口须在发布视频流之前调用。 - 调用本接口开启 Alpha 通道编码后，你需调用 [pushExternalVideoFrame](#RTCEngine-pushexternalvideoframe) 把自定义采集的视频帧推送至 RTC SDK。若推送了不支持的视频帧格式，则调用 [pushExternalVideoFrame](#RTCEngine-pushexternalvideoframe) 时会返回错误码 ReturnStatus.RETURN_STATUS_PARAMETER_ERR。 ### disableAlphaChannelVideoEncode ```java public abstract int com.ss.bytertc.engine.RTCEngine.disableAlphaChannelVideoEncode() ``` > Available since 3.58 关闭外部采集视频帧的 Alpha 通道编码功能。 **返回值** 方法调用结果： - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 该接口须在停止发布视频流之后调用。 ### sendSEIMessage ```java public abstract int com.ss.bytertc.engine.RTCEngine.sendSEIMessage( byte[] message, int repeatCount, SEICountPerFrame mode ) ``` 通过视频帧发送 SEI 数据。在视频通话场景下，SEI 数据会随视频帧发送；在语音通话场景下，SDK 会自动生成一路 16px × 16px 的黑帧视频流用来发送 SEI 数据。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | message | byte[] | SEI 消息，建议每帧 SEI 数据总长度不超过 4 KB。超过长度限制的消息会被丢弃。 | | repeatCount | int | 消息发送重复次数。取值范围是 [0, max{29, \%{视频帧率}-1}]。推荐范围 [2,4]。
调用此接口后，这些 SEI 数据会添加到从当前视频帧开始的连续 `\%{repeatCount}+1` 个视频帧中。 | | mode | SEICountPerFrame | SEI 发送模式，参看 [SEICountPerFrame](70083#SEICountPerFrame)。 | **返回值** - \>= 0：将被添加到视频帧中的 SEI 的数量。 - < 0：发送失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 每秒发送的 SEI 消息数量建议不超过当前的视频帧率。在语音通话场景下，黑帧帧率为 15 fps。 - 语音通话场景中，仅支持在内部采集模式下调用该接口发送 SEI 数据。 - 视频通话场景中，使用自定义采集并通过 [pushExternalVideoFrame](#RTCEngine-pushexternalvideoframe) 推送至 SDK 的视频帧，若本身未携带 SEI 数据，也可通过本接口发送 SEI 数据；若原视频帧中已添加了 SEI 数据，则调用此方法不生效。 - 视频帧仅携带前后 2s 内收到的 SEI 数据；语音通话场景下，若调用此接口后 1min 内未有 SEI 数据发送，则 SDK 会自动取消发布视频黑帧。 - 消息发送成功后，远端会收到 [onSEIMessageReceived](70081#IRTCEngineEventHandler-onseimessagereceived) 回调。 - 语音通话切换至视频通话时，会停止使用黑帧发送 SEI 数据，自动转为用采集到的正常视频帧发送 SEI 数据。 ### startFileRecording ```java public abstract int com.ss.bytertc.engine.RTCEngine.startFileRecording( RecordingConfig config, RecordingType recordingType ) ``` 该方法将通话过程中的音视频数据录制到本地的文件中。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | config | RecordingConfig | 本地录制参数配置，参看 [RecordingConfig](70083#RecordingConfig) | | recordingType | RecordingType | 本地录制的媒体类型，参看 [RecordingType](70083#RecordingType)
注意：屏幕流仅支持录制视频（RECORD_VIDEO_ONLY）；主流支持录制所有类型。 | **返回值** 0：正常 -1：参数设置异常 -2：当前版本 SDK 不支持该特性，请联系技术支持人员 **注意** - 该方法需在进房后调用。 - 调用该方法后，你会收到 [onRecordingStateUpdate](70081#IRTCEngineEventHandler-onrecordingstateupdate) 回调。 - 如果录制正常，系统每秒钟会通过 [onRecordingProgressUpdate](70081#IRTCEngineEventHandler-onrecordingprogressupdate) 回调通知录制进度。 ### stopFileRecording ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopFileRecording() ``` 停止本地录制 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [startFileRecording](#RTCEngine-startfilerecording) 开启本地录制后，你必须调用该方法停止录制。 - 调用该方法后，你会收到 [onRecordingStateUpdate](70081#IRTCEngineEventHandler-onrecordingstateupdate) 回调提示录制结果。 ### pushExternalEncodedVideoFrame ```java public abstract int com.ss.bytertc.engine.RTCEngine.pushExternalEncodedVideoFrame( int videoIndex, RTCEncodedVideoFrame encodedVideoFrame ) ``` 推送自定义编码后的视频流 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | videoIndex | int | 对应的编码流下标，从 0 开始，如果调用 [setVideoEncoderConfig](#RTCEngine-setvideoencoderconfig) 设置了多路流，此处数量须与之保持一致 | | encodedVideoFrame | RTCEncodedVideoFrame | 编码流视频帧信息，参看 [RTCEncodedVideoFrame](70083#RTCEncodedVideoFrame)。 | **返回值** 方法调用结果： - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** - 目前仅支持推送 H264 和 ByteVC1 格式的视频帧，且视频流协议格式须为 Annex B 格式。 - 该函数运行在用户调用线程内 - 推送自定义编码视频帧前，必须调用 [setVideoSourceType](#RTCEngine-setvideosourcetype) 将视频输入源切换至自定义编码视频源。 ### startScreenCapture ```java public abstract int com.ss.bytertc.engine.RTCEngine.startScreenCapture( ScreenMediaType type, Intent mediaProjectionResultData ) ``` 使用 RTC SDK 内部采集模块开始采集屏幕音频流和（或）视频流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | ScreenMediaType | 媒体类型，参看 [ScreenMediaType](70083#ScreenMediaType)。 | | mediaProjectionResultData | Intent | 向 Android 设备申请屏幕共享权限后，拿到的 Intent 数据，参看 [getMediaProjection](https://developer.android.com/reference/android/media/projection/MediaProjectionManager#getMediaProjection(int,\%20android.content.Intent))。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用本接口时，采集模式应为内部模式。在外部采集模式下调用无效，并将触发 [onVideoDeviceWarning](70081#IRTCEngineEventHandler-onvideodevicewarning) 或 [onAudioDeviceWarning](70081#IRTCEngineEventHandler-onaudiodevicewarning) 回调。 - 采集后，你还需要调用 [publishStreamAudio](#RTCRoom-publishstreamaudio) 和 [publishStreamVideo](#RTCRoom-publishstreamvideo) 发布采集到的屏幕音视频。 - 开启屏幕音频/视频采集成功后，本地用户会收到 [onVideoDeviceStateChanged](70081#IRTCEngineEventHandler-onvideodevicestatechanged) 和 [onAudioDeviceStateChanged](70081#IRTCEngineEventHandler-onaudiodevicestatechanged) 的回调。 - 要关闭屏幕音视频内部采集，调用 [stopScreenCapture](#RTCEngine-stopscreencapture)。 ### updateScreenCapture ```java public abstract int com.ss.bytertc.engine.RTCEngine.updateScreenCapture(ScreenMediaType type) ``` 使用 RTC SDK 内部屏幕采集后，更新采集的媒体类型。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | ScreenMediaType | 媒体类型，指定屏幕采集媒体类型，参看 [ScreenMediaType](70083#ScreenMediaType)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 在 [startScreenCapture](#RTCEngine-startscreencapture) 后调用该方法。 ### stopScreenCapture ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopScreenCapture() ``` 在屏幕共享时，停止使用 RTC SDK 内部采集方式采集屏幕音视频。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用本接口时，采集模式应为内部模式。在外部采集模式下调用无效，并将触发 [onVideoDeviceWarning](70081#IRTCEngineEventHandler-onvideodevicewarning) 或 [onAudioDeviceWarning](70081#IRTCEngineEventHandler-onaudiodevicewarning) 回调。 - 要开始屏幕音视频内部采集，调用 [startScreenCapture](#RTCEngine-startscreencapture)。 ### setVideoWatermark ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVideoWatermark( String imagePath, RTCWatermarkConfig watermarkConfig ) ``` 在指定视频流上添加水印。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | imagePath | String | 水印图片路径，支持本地文件绝对路径、Asset 资源路径（/assets/xx.png）、URI 地址（content://），长度限制为 512 字节。
水印图片为 PNG 或 JPG 格式。 | | watermarkConfig | RTCWatermarkConfig | 水印参数，参看 [RTCWatermarkConfig](70083#RTCWatermarkConfig)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [clearVideoWatermark](#RTCEngine-clearvideowatermark) 移除指定视频流的水印。 - 同一路流只能设置一个水印，新设置的水印会代替上一次的设置。你可以多次调用本方法来设置不同流的水印。 - 进入房间前后均可调用此方法。 - 若开启本地预览镜像，或开启本地预览和编码传输镜像，则远端水印均不镜像；在开启本地预览水印时，本端水印会镜像。 - 开启大小流后，水印对大小流均生效，且针对小流进行等比例缩小。 ### clearVideoWatermark ```java public abstract int com.ss.bytertc.engine.RTCEngine.clearVideoWatermark() ``` 移除指定视频流的水印。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### setDummyCaptureImagePath ```java public abstract int com.ss.bytertc.engine.RTCEngine.setDummyCaptureImagePath(String filePath) ``` 摄像头处于关闭状态时，使用静态图片填充本地推送的视频流。调用 `stopVideoCapture` 接口时，会开始推静态图片。若要停止发送图片，可传入空字符串或启用内部摄像头采集。可重复调用该接口来更新图片。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | filePath | String | 设置静态图片的路径。
支持本地文件绝对路径和 Asset 资源路径(/assets/xx.png)，不支持网络链接，长度限制为 512 字节。
静态图片支持类型为 JPEG/JPG、PNG、BMP。
若图片宽高比与设置的编码宽高比不一致，图片会被等比缩放，黑边填充空白区域。推流帧率与码率与设置的编码参数一致。 | **返回值** - 0：成功。 - -2：失败。确保传入的 filePath 为有效路径。 - -12：本方法不支持在 Audio SDK 中使用。 **注意** - 该接口只适用于 SDK 内部摄像头采集，不适用于自定义视频采集。 - 本地预览无法看到静态图片。 - 进入房间前后均可调用此方法。在多房间场景中，静态图片仅在发布的房间中生效。 - 针对该静态图片，滤镜和镜像效果不生效，水印效果生效。 - 只有主流能设置静态图片，屏幕流不支持设置。 - 开启大小流后，静态图片对大小流均生效，且针对小流进行等比例缩小。 ### takeLocalSnapshot ```java public abstract long com.ss.bytertc.engine.RTCEngine.takeLocalSnapshot(ISnapshotResultCallback callback) ``` 截取本地视频画面 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | callback | ISnapshotResultCallback | 本地截图的回调。参看 [ISnapshotResultCallback](70081#ISnapshotResultCallback)。 | **返回值** 本地截图任务的编号，从 `1` 开始递增。 **注意** - 对截取的画面，包含本地视频处理的全部效果，包含旋转，镜像，美颜等。 - 不管采用 SDK 内部采集，还是自定义采集，都可以进行截图。 ### takeRemoteSnapshot ```java public abstract long com.ss.bytertc.engine.RTCEngine.takeRemoteSnapshot( String streamId, ISnapshotResultCallback callback ) ``` 截取本地视频画面 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 远端用户的 streamId。 | | callback | ISnapshotResultCallback | 本地截图的回调。参看 [ISnapshotResultCallback](70081#ISnapshotResultCallback)。 | **返回值** 本地截图任务的编号，从 `1` 开始递增。 **注意** - 对截取的画面，包含本地视频处理的全部效果，包含旋转，镜像，美颜等。 - 不管采用 SDK 内部采集，还是自定义采集，都可以进行截图。 ### takeRemoteSnapshotToFile ```java public abstract long com.ss.bytertc.engine.RTCEngine.takeRemoteSnapshotToFile( String streamId, String filePath ) ``` 截取远端的视频流画面，生成 JPG 文件，并保存到本地指定路径。调用该方法后，SDK 会触发回调 [onRemoteSnapshotTakenToFile](70081#IRTCEngineEventHandler-onremotesnapshottakentofile) 报告截图是否成功，以及截取的图片信息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 待截取的远端视频流 ID。 | | filePath | String | 截图的本地保存路径（绝对路径），需精确到文件名及格式，文件扩展名必须为 `.jpg`，并请确保路径存在且可写。示例：`/sdcard/Pictures/snapshot.jpg`。 | **返回值** 远端截图任务的编号，从 `1` 开始递增。此编号可用于追踪任务状态或进行其他管理操作。 ### takeLocalSnapshotToFile ```java public abstract long com.ss.bytertc.engine.RTCEngine.takeLocalSnapshotToFile(String filePath) ``` 截取本地的视频流画面，生成 JPG 文件，并保存到本地指定路径。调用该方法后，SDK 会触发回调 [onLocalSnapshotTakenToFile](70081#IRTCEngineEventHandler-onlocalsnapshottakentofile) 报告截图是否成功，以及截取的图片信息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | filePath | String | 截图的本地保存路径（绝对路径），需精确到文件名及格式，文件扩展名必须为 `.jpg`，并请确保路径存在且可写。示例：`/sdcard/Pictures/snapshot.jpg`。 | **返回值** 远端截图任务的编号，从 `1` 开始递增。此编号可用于追踪任务状态或进行其他管理操作。 ### startEchoTest ```java public abstract int com.ss.bytertc.engine.RTCEngine.startEchoTest( EchoTestConfig config, int delayTime ) ``` 开启音视频回路测试。在进房前，用户可调用该接口对音视频通话全链路进行检测，包括对音视频设备以及用户上下行网络的检测，从而帮助用户判断是否可以正常发布和接收音视频流。开始检测后，SDK 会录制你声音或视频。如果你在设置的延时范围内收到了回放，则视为音视频回路测试正常。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | config | EchoTestConfig | 回路测试参数设置，参看 [EchoTestConfig](70083#EchoTestConfig)。 | | delayTime | int | 音视频延迟播放的时间间隔，用于指定在开始检测多长时间后期望收到回放。取值范围为 [2,10]，单位为秒，默认为 2 秒。 | **返回值** 方法调用结果： - 0：成功 - -2：失败，参数异常 - -4：失败，用户已进房 - -6：失败，当前用户已经在检测中 - -7：失败，音视频均不检查 - -8：失败，已经存在相同 roomId 的房间 **注意** - 调用该方法开始音视频回路检测后，你可以调用 [stopEchoTest](#RTCEngine-stopechotest) 立即结束测试，也可等待测试 60s 后自动结束，以更换设备进行下一次测试，或进房。 - 在该方法之前调用的所有跟设备控制、流控制相关的方法均在开始检测时失效，在结束检测后恢复生效。 - 在调用 [startEchoTest](#RTCEngine-startechotest) 和 [stopEchoTest](#RTCEngine-stopechotest) 之间调用的所有跟设备采集、流控制、进房相关的方法均不生效，并会收到 [onWarning](70081#IRTCEngineEventHandler-onwarning) 回调，提示警告码为 `WARNING_CODE_IN_ECHO_TEST_MODE`。 - 音视频回路检测的结果会通过 [onEchoTestResult](70081#IRTCEngineEventHandler-onechotestresult) 回调通知。 ### stopEchoTest ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopEchoTest() ``` 停止音视频回路测试。调用 [startEchoTest](#RTCEngine-startechotest) 开启音视频回路检测后，你必须调用该方法停止检测。 **返回值** 方法调用结果： - 0：成功。 - -3：失败，未开启回路检测。 **注意** 音视频回路检测结束后，所有对系统设备及音视频流的控制均会恢复到开始检测前的状态。 ### setRemoteVideoSink ```java public abstract int com.ss.bytertc.engine.RTCEngine.setRemoteVideoSink( String streamId, IVideoSink videoSink, RemoteVideoSinkConfig config ) ``` > Available since 3.57 将远端视频流与自定义渲染器绑定。你可以通过参数设置返回指定位置和格式的视频帧数据。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 流 ID，用于指定需要渲染的视频流。 | | videoSink | IVideoSink | 自定义视频渲染器，参看 [IVideoSink](70083#IVideoSink)。 | | config | RemoteVideoSinkConfig | 远端视频帧回调配置，参看 [RemoteVideoSinkConfig](70083#RemoteVideoSinkConfig)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - RTC SDK 默认使用自带的渲染器（内部渲染器）进行视频渲染。 - 该方法进房前后均可以调用。若想在进房前调用，你需要在加入房间前获取远端流信息；若无法预先获取远端流信息，你可以在加入房间并通过 [onUserPublishStreamVideo](70081#IRTCRoomEventHandler-onuserpublishstreamvideo) 回调获取到远端流信息之后，再调用该方法。 - 退房时将清除绑定状态。 - 如果需要解除绑定，你必须将 videoSink 设置为 null。 ### updateRemoteStreamVideoCanvas ```java public abstract int com.ss.bytertc.engine.RTCEngine.updateRemoteStreamVideoCanvas( String streamId, RemoteVideoRenderConfig remoteVideoRenderConfig ) ``` > Available since 3.56 使用 SDK 内部渲染时，修改远端视频帧的渲染设置，包括渲染模式、背景颜色和旋转角度。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 流 ID，用于指定需要修改渲染设置的视频流。 | | remoteVideoRenderConfig | RemoteVideoRenderConfig | 视频帧渲染设置。具体参看 [RemoteVideoRenderConfig](70083#RemoteVideoRenderConfig)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [setRemoteVideoCanvas](#RTCEngine-setremotevideocanvas) 设置了远端视频渲染模式后，你可以调用此接口更新渲染模式、背景颜色、旋转角度的设置。 - 该接口可以在远端视频渲染过程中调用，调用结果会实时生效。 ### setRemoteVideoCanvas ```java public abstract int com.ss.bytertc.engine.RTCEngine.setRemoteVideoCanvas( String streamId, VideoCanvas videoCanvas ) ``` 渲染来自指定远端用户的视频流时，设置使用的视图和渲染模式。要解除绑定，将 `videoCanvas` 设置为空。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 流 ID，用于指定需要设置视图和渲染模式的视频流。 | | videoCanvas | VideoCanvas | 视图信息和渲染模式，参看 [VideoCanvas](70083#VideoCanvas)。3.56 版本起支持通过 `renderRotation` 设置远端视频渲染的旋转角度。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 本地用户离开房间时，会解除调用此 API 建立的绑定关系；远端用户离开房间则不会影响。 ### setRemoteAudioPlaybackVolume ```java public abstract int com.ss.bytertc.engine.RTCEngine.setRemoteAudioPlaybackVolume( String streamId, int volume ) ``` 调节本端播放收到的远端流时的音量。你必须在进房后进行设置。流的发布状态改变不影响设置生效。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 流 ID，用于指定要调节音量的远端流。 | | volume | int | 音量值和原始音量的比值，范围是 [0, 400]，单位为 \%，自带溢出保护。
为保证更好的通话质量，建议将 volume 值设为 [0,100]。 | **返回值** 方法调用结果： - 0：成功。 - < 0：失败。具体失败原因参看 [ReturnStatus](70083#ReturnStatus)。 **注意** 假设某远端用户 A 始终在被调节的目标用户范围内： - 当该方法与 [setRemoteRoomAudioPlaybackVolume](#RTCRoom-setremoteroomaudioplaybackvolume) 共同使用时，本地收听用户 A 的音量为后调用的方法设置的音量； - 当该方法与 [setPlaybackVolume](#RTCEngine-setplaybackvolume) 方法共同使用时，本地收听用户 A 的音量将为两次设置的音量效果的叠加。 - 当你调用该方法设置远端流音量后，如果远端退房，接口设置失效。 ### setVideoDecoderConfig ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVideoDecoderConfig( String streamId, VideoDecoderConfig config ) ``` 在订阅远端视频流之前，设置远端视频数据解码方式 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 远端流 ID，指定对哪一路视频流进行解码方式设置 | | config | VideoDecoderConfig | 视频解码方式，参看 [VideoDecoderConfig](70083#VideoDecoderConfig)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 当你想要对远端流进行自定义解码时，你需要先调用 [registerRemoteEncodedVideoFrameObserver](#RTCEngine-registerremoteencodedvideoframeobserver) 注册远端视频流监测器，然后再调用该接口将解码方式设置为自定义解码。监测到的视频数据会通过 [onRemoteEncodedVideoFrame](70081#IRemoteEncodedVideoFrameObserver-onremoteencodedvideoframe) 回调出来。 - 自 3.56 起，要用于自动订阅场景下，你可以设置 `key` 中的 `RoomId` 和 `UserId` 为 `nullptr`，此时，通过此接口设置的解码方式根据 `key` 中的 `StreamIndex` 值，适用于所有的远端主流或屏幕流的解码方式。 ### requestRemoteVideoKeyFrame ```java public abstract int com.ss.bytertc.engine.RTCEngine.requestRemoteVideoKeyFrame(String streamId) ``` 在订阅远端视频流之后，向远端请求关键帧 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 远端流 ID。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 该方法仅适用于手动订阅模式，并且在成功订阅远端流之后使用。 - 该方法适用于调用 [setVideoDecoderConfig](#RTCEngine-setvideodecoderconfig) 开启自定义解码功能后，并且自定义解码失败的情况下使用 ### startCloudProxy ```java public abstract int com.ss.bytertc.engine.RTCEngine.startCloudProxy(List cloudProxiesInfo) ``` 开启云代理 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | cloudProxiesInfo | List\ | 云代理服务器信息列表。参看 [CloudProxyInfo](70083#CloudProxyInfo)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 在加入房间前调用此接口 - 在开启云代理后，进行通话前网络探测 - 开启云代理后，并成功链接云代理服务器后，会收到 [onCloudProxyConnected](70081#IRTCEngineEventHandler-oncloudproxyconnected)。 - 要关闭云代理，调用 [stopCloudProxy](#RTCEngine-stopcloudproxy)。 ### stopCloudProxy ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopCloudProxy() ``` 关闭云代理 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 要开启云代理，调用 [startCloudProxy](#RTCEngine-startcloudproxy)。 ### getNetworkTimeInfo ```java public abstract NetworkTimeInfo com.ss.bytertc.engine.RTCEngine.getNetworkTimeInfo() ``` 通过 NTP 协议，获取网络时间。 **返回值** 网络时间。参看 [NetworkTimeInfo](70083#NetworkTimeInfo)。 **注意** - 第一次调用此接口会启动网络时间同步功能，并返回 `0`。同步完成后，会收到 [onNetworkTimeSynchronized](70081#IRTCEngineEventHandler-onnetworktimesynchronized)，此后，再次调用此 API，即可获取准确的网络时间。 - 在合唱场景下，合唱参与者应在相同的网络时间播放背景音乐。 ### getWTNStream ```java public abstract IWTNStream com.ss.bytertc.engine.RTCEngine.getWTNStream() ``` 获取 WTN 管理接口。 **返回值** WTN 管理接口，参看 [IWTNStream](#IWTNStream)。 ### startHardwareEchoDetection ```java public abstract int com.ss.bytertc.engine.RTCEngine.startHardwareEchoDetection(String testAudioFilePath) ``` 开启通话前回声检测 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | testAudioFilePath | String | 用于回声检测的音频文件的绝对路径，路径字符串使用 UTF-8 编码格式，支持以下音频格式：mp3，aac，m4a，3gp，wav。
音频文件不为静音文件，推荐时长为 10 ～ 20 秒。 | **返回值** 方法调用结果： - 0：成功。 - -1：失败。上一次检测未结束，请先调用 [stopHardwareEchoDetection](#RTCEngine-stophardwareechodetection) 停止检测后重新调用本接口。 - -2：失败。路径不合法或音频文件格式不支持。 **注意** - 只有当 [ChannelProfile](70083#ChannelProfile) 为 `CHANNEL_PROFIEL_MEETING` 和 `CHANNEL_PROFILE_MEETING_ROOM` 时支持开启本功能。 - 开启检测前，你需要向用户获取音频设备的使用权限。 - 开启检测前，请确保音频设备没有被静音，采集和播放音量正常。 - 调用本接口后监听 onHardwareEchoDetectionResult 获取检测结果。 - 检测期间，进程将独占音频设备，无法使用其他音频设备测试接口：[startEchoTest](#RTCEngine-startechotest)、[startAudioDeviceRecordTest](#IRTCAudioDeviceManager-startaudiodevicerecordtest) 或 [startAudioPlaybackDeviceTest](#IRTCAudioDeviceManager-startaudioplaybackdevicetest)。 - 调用 [stopHardwareEchoDetection](#RTCEngine-stophardwareechodetection) 停止检测，释放对音频设备的占用。 ### stopHardwareEchoDetection ```java public abstract int com.ss.bytertc.engine.RTCEngine.stopHardwareEchoDetection() ``` 停止通话前回声检测 **返回值** 方法调用结果： - 0：成功。 - -1：失败。 **注意** - 关于开启通话前回声检测，参看 [startHardwareEchoDetection](#RTCEngine-starthardwareechodetection) 。 - 建议在收到 [onHardwareEchoDetectionResult](70081#IRTCEngineEventHandler-onhardwareechodetectionresult) 通知的检测结果后，调用本接口停止检测。 - 在用户进入房间前结束回声检测，释放对音频设备的占用，以免影响正常通话。 ### setCellularEnhancement ```java public abstract int com.ss.bytertc.engine.RTCEngine.setCellularEnhancement(MediaTypeEnhancementConfig config) ``` 启用蜂窝网络辅助增强，改善通话质量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | config | MediaTypeEnhancementConfig | 参看 [MediaTypeEnhancementConfig](70083#MediaTypeEnhancementConfig)。 | **返回值** 方法调用结果： - 0：成功。 - -1：失败，内部错误。 - -2：失败，输入参数错误。 **注意** 此功能默认不开启。 ### setLocalProxy ```java public abstract int com.ss.bytertc.engine.RTCEngine.setLocalProxy(List configurations) ``` 设置本地代理。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | configurations | List\ | 本地代理配置参数。参看 [LocalProxyConfiguration](70083#LocalProxyConfiguration)。
你可以根据自己的需要选择同时设置 Http 隧道和 Socks5 两类代理，或者单独设置其中一类代理。如果你同时设置了 Http 隧道和 Socks5 两类代理，此时，媒体和信令采用 Socks5 代理， Http 请求采用 Http 隧道代理；如果只设置 Http 隧道或 Socks5 一类代理，媒体、信令和 Http 请求均采用已设置的代理。
调用此接口设置本地代理后，若想清空当前已有的代理设置，可再次调用此接口，选择不设置任何代理即可清空。 | **注意** - 该方法需要在进房前调用。 - 调用该方法设置本地代理后，SDK 会触发 [onLocalProxyStateChanged](70081#IRTCEngineEventHandler-onlocalproxystatechanged) ，返回代理连接的状态。 ### getVideoDeviceManager ```java public abstract IVideoDeviceManager com.ss.bytertc.engine.RTCEngine.getVideoDeviceManager() ``` > Available since 3.56 创建视频设备管理实例 **返回值** 视频设备管理实例，详见 [IVideoDeviceManager](#IVideoDeviceManager) ### setVideoCaptureRotation ```java public abstract int com.ss.bytertc.engine.RTCEngine.setVideoCaptureRotation(VideoRotation rotation) ``` 设置本端采集的视频帧的旋转角度。当摄像头倒置或者倾斜安装时，可调用本接口进行调整。对于手机等普通设备，可调用 [setVideoRotationMode](#RTCEngine-setvideorotationmode) 实现旋转。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | rotation | VideoRotation | 相机朝向角度，默认为 `VIDEO_ROTATION_0(0)`，无旋转角度。详见 [VideoRotation](70083#VideoRotation)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 对于内部采集的视频画面，如果已调用 [setVideoRotationMode](#RTCEngine-setvideorotationmode) 设置了旋转方向，会在此基础上叠加旋转角度。 - 调用本接口也将对自定义采集视频画面生效，在原有的旋转角度基础上叠加本次设置。 - 视频贴纸特效或通过 [enableVirtualBackground](#IVideoEffect-enablevirtualbackground) 增加的虚拟背景，也会跟随本接口的设置进行旋转。 - 本地渲染视频和发送到远端的视频都会相应旋转，但不会应用到单流转推中。如果希望在单流转推的视频中应用旋转，调用 [setVideoOrientation](#RTCEngine-setvideoorientation)。 ### setLocalVideoSink ```java public abstract int com.ss.bytertc.engine.RTCEngine.setLocalVideoSink( IVideoSink videoSink, @IVideoSink.PixelFormat int requiredFormat ) ``` > Deprecated since 3.60, use setLocalVideoSink(IVideoSink videoSink, LocalVideoSinkConfig config) instead. 将本地视频流与自定义渲染器绑定。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | videoSink | IVideoSink | 自定义视频渲染器，参看 [IVideoSink](70083#IVideoSink) | | requiredFormat | @IVideoSink.PixelFormat int | videoSink 适用的视频帧编码格式，参看 [PixelFormat](70083#PixelFormat) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - RTC SDK 默认使用自带的渲染器（内部渲染器）进行视频渲染。 - 退房时将清除绑定状态。 - 如果需要解除绑定，你必须将 videoSink 设置为 null。 - 一般在收到 [onFirstLocalVideoFrameCaptured](70081#IRTCEngineEventHandler-onfirstlocalvideoframecaptured) 回调通知完成本地视频首帧采集后，调用此方法为视频流绑定自定义渲染器；然后加入房间。 - 本方法获取的是前处理后的视频帧。 ### setRemoteVideoSink ```java public abstract int com.ss.bytertc.engine.RTCEngine.setRemoteVideoSink( String streamId, IVideoSink videoSink, @IVideoSink.PixelFormat int requiredFormat ) ``` > Deprecated since 3.57, use [setRemoteVideoSink](#RTCEngine-setremotevideosink) instead. 将远端视频流与自定义渲染器绑定。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 流 ID，用于指定需要渲染的视频流。 | | videoSink | IVideoSink | 自定义视频渲染器，参看 [IVideoSink](70083#IVideoSink) | | requiredFormat | @IVideoSink.PixelFormat int | videoSink 适用的视频帧编码格式，参看 [PixelFormat](70083#PixelFormat) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - RTC SDK 默认使用 RTC SDK 自带的渲染器（内部渲染器）进行视频渲染。 - 该方法进房前后均可以调用。若想在进房前调用，你需要在加入房间前获取远端流信息；若无法预先获取远端流信息，你可以在加入房间并通过 [onUserPublishStreamVideo](70081#IRTCRoomEventHandler-onuserpublishstreamvideo) 回调获取到远端流信息之后，再调用该方法。 - 如果需要解除绑定，你必须将 videoSink 设置为 null。退房时将清除绑定状态。 - 本方法获取的是后处理后的视频帧。 ### updateRemoteStreamVideoCanvas ```java public abstract int com.ss.bytertc.engine.RTCEngine.updateRemoteStreamVideoCanvas( String streamId, int renderMode, int backgroundColor ) ``` > Deprecated since 3.56 and will be deleted in 3.62. Use [updateRemoteStreamVideoCanvas](#updateremotestreamvideocanvas-2) instead. 修改远端视频帧的渲染设置，包括渲染模式和背景颜色。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamId | String | 流 ID，用于指定需要修改渲染设置的视频流。 | | renderMode | int | 渲染模式，参看 [VideoCanvas](70083#VideoCanvas).renderMode | | backgroundColor | int | 背景颜色，参看 [VideoCanvas](70083#VideoCanvas).backgroundColor | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 你可以在远端视频渲染过程中，调用此接口。调用结果会实时生效。 # IMediaPlayer ```java public abstract class com.ss.bytertc.engine.audio.IMediaPlayer ``` > Available since 3.53 音乐播放器调用 [setEventHandler](#IMediaPlayer-seteventhandler) 设置回调句柄以获取相关回调。 ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract int | [open](#IMediaPlayer-open) | | abstract int | [start](#IMediaPlayer-start) | | abstract int | [openWithCustomSource](#IMediaPlayer-openwithcustomsource) | | abstract int | [stop](#IMediaPlayer-stop) | | abstract int | [pause](#IMediaPlayer-pause) | | abstract int | [resume](#IMediaPlayer-resume) | | abstract int | [setVolume](#IMediaPlayer-setvolume) | | abstract int | [getVolume](#IMediaPlayer-getvolume) | | abstract int | [getTotalDuration](#IMediaPlayer-gettotalduration) | | abstract int | [getPlaybackDuration](#IMediaPlayer-getplaybackduration) | | abstract int | [getPosition](#IMediaPlayer-getposition) | | abstract PlayerState | [getState](#IMediaPlayer-getstate) | | abstract int | [setAudioPitch](#IMediaPlayer-setaudiopitch) | | abstract int | [setPosition](#IMediaPlayer-setposition) | | abstract int | [setAudioDualMonoMode](#IMediaPlayer-setaudiodualmonomode) | | abstract int | [getAudioTrackCount](#IMediaPlayer-getaudiotrackcount) | | abstract int | [selectAudioTrack](#IMediaPlayer-selectaudiotrack) | | abstract int | [setPlaybackSpeed](#IMediaPlayer-setplaybackspeed) | | abstract int | [setProgressInterval](#IMediaPlayer-setprogressinterval) | | abstract int | [setLoudness](#IMediaPlayer-setloudness) | | abstract int | [registerAudioFrameObserver](#IMediaPlayer-registeraudioframeobserver) | | abstract int | [pushExternalAudioFrame](#IMediaPlayer-pushexternalaudioframe) | | abstract int | [setEventHandler](#IMediaPlayer-seteventhandler) | ## 函数说明 ### open ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.open( String filePath, MediaPlayerConfig config ) ``` 打开音乐文件。一个播放器实例仅能够同时打开一个音乐文件。如果需要同时打开多个音乐文件，请创建多个音乐播放器实例。要播放 PCM 格式的音频数据，参看 [openWithCustomSource](#IMediaPlayer-openwithcustomsource)。`openWithCustomSource` 和此 API 互斥。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | filePath | String | 音乐文件路径。
支持在线文件的 URL、本地文件的 URI、本地文件的绝对路径或以 `/assets/` 开头的本地文件路径。对于在线文件的 URL，仅支持 https 协议。
推荐的采样率：8KHz、16KHz、22.05KHz、44.1KHz、48KHz。
不同平台支持的本地文件格式：

	mp3	mp4	aac	m4a	3gp	wav	ogg	ts	wma
Android	Y	Y	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y	Y	Y	Y
Windows	Y	Y	Y	Y	Y	Y		Y	Y

不同平台支持的在线文件格式：

	mp3	aac	m4a	3gp	wav	ts	wma
Android	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y		Y
Windows	Y	Y	Y	Y	Y	Y	Y

| | config | MediaPlayerConfig | 详见 [MediaPlayerConfig](70083#MediaPlayerConfig)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### start ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.start() ``` 播放音乐。你仅需要在调用 [open](#IMediaPlayer-open)，且未开启自动播放时，调用此方法。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 要播放 PCM 格式的音频数据，参看 [openWithCustomSource](#IMediaPlayer-openwithcustomsource)。`openWithCustomSource` 和此 API 互斥。 - 调用本方法播放音频文件后，可调用 [stop](#IMediaPlayer-stop) 方法暂停播放。 ### openWithCustomSource ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.openWithCustomSource( MediaPlayerCustomSource source, MediaPlayerConfig config ) ``` 启动音频裸数据混音。要播放音乐文件，参看 [open](#IMediaPlayer-open)。`open` 与此 API 互斥。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | source | MediaPlayerCustomSource | 数据源，详见 [MediaPlayerCustomSource](70083#MediaPlayerCustomSource) | | config | MediaPlayerConfig | 详见 [MediaPlayerConfig](70083#MediaPlayerConfig) | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用本方法启动后，再调用 [pushExternalAudioFrame](#IMediaPlayer-pushexternalaudioframe) 推送音频数据，才会开始混音。 - 如要结束 PCM 音频数据混音，调用 [stop](#IMediaPlayer-stop)。 ### stop ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.stop() ``` 调用 [open](#IMediaPlayer-open), [start](#IMediaPlayer-start), 或 [openWithCustomSource](#IMediaPlayer-openwithcustomsource) 开始播放后，可以调用本方法停止。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### pause ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.pause() ``` 调用 [open](#IMediaPlayer-open)，或 [start](#IMediaPlayer-start) 开始播放音频文件后，调用本方法暂停播放。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用本方法暂停播放后，可调用 [resume](#IMediaPlayer-resume) 恢复播放。 - 此接口仅支持音频文件，不支持 PCM 数据。 ### resume ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.resume() ``` 调用 [pause](#IMediaPlayer-pause) 暂停音频播放后，调用本方法恢复播放。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 此接口仅支持音频文件，不支持 PCM 数据。 ### setVolume ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.setVolume( int volume, AudioMixingType type ) ``` 调节指定混音的音量大小，包括音乐文件混音和 PCM 混音。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 播放音量相对原音量的比值。单位为 \%。范围为 `[0, 400]`，建议范围是 `[0, 100]`。带溢出保护。 | | type | AudioMixingType | 详见 [AudioMixingType](70083#AudioMixingType)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 如果在起播前调用此接口，设置的参数值将被缓存，在起播后生效。 ### getVolume ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.getVolume(AudioMixingType type) ``` 获取当前音量 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | AudioMixingType | 详见 [AudioMixingType](70083#AudioMixingType)。 | **返回值** - \>0：成功, 当前音量值。 - < 0：失败 **注意** 仅在音频播放进行状态时，调用此方法。包括音乐文件混音和 PCM 混音。 ### getTotalDuration ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.getTotalDuration() ``` 获取音乐文件时长。 **返回值** - \>0：成功, 音乐文件时长，单位为毫秒。 - < 0：失败 **注意** - 仅在音频播放进行状态时，调用此方法。 - 此接口仅支持音频文件，不支持 PCM 数据。 ### getPlaybackDuration ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.getPlaybackDuration() ``` 获取混音音乐文件的实际播放时长，单位为毫秒。 **返回值** - \>0：实际播放时长。 - < 0：失败。 **注意** - 实际播放时长指的是歌曲不受停止、跳转、倍速、卡顿影响的播放时长。例如，若歌曲正常播放到 1:30 时停止播放 30s 或跳转进度到 2:00, 随后继续正常播放 2 分钟，则实际播放时长为 3 分 30 秒。 - 仅在音频播放进行状态，且 [setProgressInterval](#IMediaPlayer-setprogressinterval) 设置间隔大于 `0` 时，调用此方法。 - 此接口仅支持音频文件，不支持 PCM 数据。 ### getPosition ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.getPosition() ``` 获取音乐文件播放进度。 **返回值** - \>0：成功, 音乐文件播放进度，单位为毫秒。 - < 0：失败 **注意** - 仅在音频播放进行状态时，调用此方法。 - 此接口仅支持音频文件，不支持 PCM 数据。 ### getState ```java public abstract PlayerState com.ss.bytertc.engine.audio.IMediaPlayer.getState() ``` > Available since 3.59 获取播放器状态 **返回值** 播放器当前状态，参看 [PlayerState](70083#PlayerState)。 **注意** 仅在音频实例创建后，调用此方法。 ### setAudioPitch ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.setAudioPitch(int pitch) ``` 开启变调功能，多用于 K 歌场景。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | pitch | int | 与音乐文件原始音调相比的升高/降低值，取值范围为 `[-12，12]`，默认值为 0。每相邻两个值的音高距离相差半音，正值表示升调，负值表示降调。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 如果在起播前调用此接口，设置的参数值将被缓存，在起播后生效。 - 仅支持音乐文件混音，不支持 PCM 数据。 ### setPosition ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.setPosition(int position) ``` 设置音乐文件的起始播放位置。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | position | int | 音乐文件起始播放位置，单位为毫秒。
你可以通过 [getTotalDuration](#IMediaPlayer-gettotalduration) 获取音乐文件总时长，position 的值应小于音乐文件总时长。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 此接口仅支持音频文件，不支持 PCM 数据。 - 在播放在线文件时，调用此接口可能造成播放延迟的现象。 - 调用本接口后，会收到 [onMediaPlayerEvent](70081#IMediaPlayerEventHandler-onmediaplayerevent) 回调。 ### setAudioDualMonoMode ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.setAudioDualMonoMode(AudioMixingDualMonoMode mode) ``` 设置当前音乐文件的声道模式 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mode | AudioMixingDualMonoMode | 声道模式。默认的声道模式和源文件一致，详见 [AudioMixingDualMonoMode](70083#AudioMixingDualMonoMode)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 如果在起播前调用此接口，设置的参数值将被缓存，在起播后生效。 - 仅支持音频文件，不支持 PCM 数据。 ### getAudioTrackCount ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.getAudioTrackCount() ``` 获取当前音乐文件的音轨数 **返回值** + \>= 0：成功，返回当前音乐文件的音轨数 - < 0：方法调用失败 **注意** - 仅在音频播放进行状态时，调用此方法。 - 此方法仅支持音乐文件，不支持 PCM 数据。 ### selectAudioTrack ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.selectAudioTrack(int index) ``` 指定当前音乐文件的播放音轨 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | int | 指定的播放音轨，从 0 开始，取值范围为 `[0, getAudioTrackCount()-1]`。
设置的参数值需要小于 [getAudioTrackCount](#IMediaPlayer-getaudiotrackcount) 的返回值 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 仅在音频播放进行状态时，调用此方法。 - 此方法仅支持音乐文件，不支持 PCM 数据。 - 调用本接口后，会收到 [onMediaPlayerEvent](70081#IMediaPlayerEventHandler-onmediaplayerevent) 回调。 ### setPlaybackSpeed ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.setPlaybackSpeed(int speed) ``` 设置播放速度 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | speed | int | 播放速度与原始文件速度的比例，单位：\%，取值范围为 `[50,200]`，默认值为 100。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 如果在起播前调用此接口，设置的参数值将被缓存，在起播后生效。 - 此方法对音频文件可用，不支持 PCM 数据。 ### setProgressInterval ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.setProgressInterval(long interval) ``` 设置音频文件混音时，收到 [onMediaPlayerPlayingProgress](70081#IMediaPlayerEventHandler-onmediaplayerplayingprogress) 的间隔。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | interval | long | 时间间隔，单位毫秒。

interval \> 0 时，触发回调。实际间隔为 10 的倍数。如果输入数值不能被 10 整除，将自动向上取整。例如传入 `52`，实际间隔为 60 ms。
interval <= 0 时，不会触发回调。

| **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 如果在起播前调用此接口，设置的参数值将被缓存，在起播后生效。 - 此方法仅支持音频文件，不支持 PCM 数据。 ### setLoudness ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.setLoudness(float loudness) ``` 如果你需要使用 [enableVocalInstrumentBalance](#RTCEngine-enablevocalinstrumentbalance) 对音频文件/PCM 音频数据设置音量均衡，你必须通过此接口传入其原始响度。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | loudness | float | 原始响度，单位：lufs，取值范围为 `[-70.0, 0.0]`。
当设置的值小于 -70.0lufs 时，则默认调整为 -70.0lufs，大于 0.0lufs 时，则不对该响度做音量均衡处理。默认值为 1.0lufs，即不做处理。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 如果在起播前调用此接口，设置的参数值将被缓存，在起播后生效。 - 此方法对音频文件和音频裸数据播放都可用。 ### registerAudioFrameObserver ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.registerAudioFrameObserver(IMediaPlayerAudioFrameObserver observer) ``` 注册回调句柄以在本地音乐文件混音时，收到相关回调。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | observer | IMediaPlayerAudioFrameObserver | 参看 [IMediaPlayerAudioFrameObserver](70081#IMediaPlayerAudioFrameObserver)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 此接口仅支持音频文件，不支持 PCM 数据。 ### pushExternalAudioFrame ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.pushExternalAudioFrame(AudioFrame audioFrame) ``` 推送用于混音的 PCM 音频帧数据 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audioFrame | AudioFrame | 音频帧，详见 [AudioFrame](70083#AudioFrame)。

音频采样格式必须为 S16。音频缓冲区内的数据格式必须为 PCM，其容量大小应该为 `audioFrame.samples × audioFrame.channel × 2`。
必须指定具体的采样率和声道数，不支持设置为自动。

| **返回值** - 0：成功 - < 0：失败 **注意** - 调用该方法前，须通过 [openWithCustomSource](#IMediaPlayer-openwithcustomsource) 启动外部音频流混音。 - 使用参考建议：首次推送数据，请在应用侧先缓存一定数据（如 200 毫秒），然后一次性推送过去；此后的推送操作定时 10 毫秒一次，并且每次的音频数据量为 10 毫秒数据量。 - 如果要暂停播放，暂停推送即可。 ### setEventHandler ```java public abstract int com.ss.bytertc.engine.audio.IMediaPlayer.setEventHandler(IMediaPlayerEventHandler handler) ``` 设置回调句柄。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | handler | IMediaPlayerEventHandler | 参看 [IMediaPlayerEventHandler](70081#IMediaPlayerEventHandler)。 | **返回值** - 0：成功。 - < 0：失败。 # IAudioEffectPlayer ```java public abstract class com.ss.bytertc.engine.audio.IAudioEffectPlayer ``` > Available since 3.53 音效播放器调用 [setEventHandler](#IAudioEffectPlayer-seteventhandler) 设置回调句柄以获取相关回调。 ## 成员函数 | 返回 | 名称 | | --- | --- | | abstract int | [start](#IAudioEffectPlayer-start) | | abstract int | [stop](#IAudioEffectPlayer-stop) | | abstract int | [stopAll](#IAudioEffectPlayer-stopall) | | abstract int | [preload](#IAudioEffectPlayer-preload) | | abstract int | [unload](#IAudioEffectPlayer-unload) | | abstract int | [unloadAll](#IAudioEffectPlayer-unloadall) | | abstract int | [pause](#IAudioEffectPlayer-pause) | | abstract int | [pauseAll](#IAudioEffectPlayer-pauseall) | | abstract int | [resume](#IAudioEffectPlayer-resume) | | abstract int | [resumeAll](#IAudioEffectPlayer-resumeall) | | abstract int | [setPosition](#IAudioEffectPlayer-setposition) | | abstract int | [getPosition](#IAudioEffectPlayer-getposition) | | abstract int | [setVolume](#IAudioEffectPlayer-setvolume) | | abstract int | [setVolumeAll](#IAudioEffectPlayer-setvolumeall) | | abstract int | [getVolume](#IAudioEffectPlayer-getvolume) | | abstract int | [getDuration](#IAudioEffectPlayer-getduration) | | abstract int | [setEventHandler](#IAudioEffectPlayer-seteventhandler) | ## 函数说明 ### start ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.start( int effectId, String filePath, AudioEffectPlayerConfig config ) ``` 开始播放音效文件。可以通过传入不同的 ID 和 filepath 多次调用本方法，以实现同时播放多个音效文件，实现音效叠加。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID。用于标识音效，请保证音效 ID 唯一性。
如果使用相同的 ID 重复调用本方法后，上一个音效会停止，下一个音效开始，并收到 [onAudioEffectPlayerStateChanged](70081#IAudioEffectPlayerEventHandler-onaudioeffectplayerstatechanged)。 | | filePath | String | 音效文件路径。
支持在线文件的 URL、本地文件的 URI、本地文件的绝对路径或以 `/assets/` 开头的本地文件路径。对于在线文件的 URL，仅支持 https 协议。
推荐的音效文件采样率：8KHz、16KHz、22.05KHz、44.1KHz、48KHz。
不同平台支持的本地音效文件格式：

	mp3	mp4	aac	m4a	3gp	wav	ogg	ts	wma
Android	Y	Y	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y	Y	Y	Y
Windows	Y	Y	Y	Y	Y	Y		Y	Y

不同平台支持的在线音效文件格式：

	mp3	aac	m4a	3gp	wav	ts	wma
Android	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y		Y
Windows	Y	Y	Y	Y	Y	Y	Y

| | config | AudioEffectPlayerConfig | 音效配置，详见 [AudioEffectPlayerConfig](70083#AudioEffectPlayerConfig)。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 如果已经通过 [preload](#IAudioEffectPlayer-preload) 将文件加载至内存，确保此处的 ID 与 [preload](#IAudioEffectPlayer-preload) 设置的 ID 相同。 - 开始播放音效文件后，可以调用 [stop](#IAudioEffectPlayer-stop) 方法停止播放音效文件。 ### stop ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.stop(int effectId) ``` 停止播放音效文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [start](#IAudioEffectPlayer-start) 方法开始播放音效文件后，可以调用本方法停止播放音效文件。 - 调用本方法停止播放音效文件后，该音效文件会被自动卸载。 ### stopAll ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.stopAll() ``` 停止播放所有音效文件。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [start](#IAudioEffectPlayer-start) 方法开始播放音效文件后，可以调用本方法停止播放所有音效文件。 - 调用本方法停止播放所有音效文件后，该音效文件会被自动卸载。 ### preload ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.preload( int effectId, String filePath ) ``` 预加载指定音乐文件到内存中，以避免频繁播放同一文件时的重复加载，减少 CPU 占用。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID。用于标识音效，请保证音效 ID 唯一性。
如果使用相同的 ID 重复调用本方法，后一次会覆盖前一次。
如果先调用 [start](#IAudioEffectPlayer-start)，再使用相同的 ID 调用本方法，会收到回调 [onAudioEffectPlayerStateChanged](70081#IAudioEffectPlayerEventHandler-onaudioeffectplayerstatechanged) ，通知前一个音效停止，然后加载下一个音效。
调用本方法预加载 A.mp3 后，如果需要使用相同的 ID 调用 [start](#IAudioEffectPlayer-start) 播放 B.mp3，请先调用 [unload](#IAudioEffectPlayer-unload) 卸载 A.mp3 ，否则会报错 AUDIO_MIXING_ERROR_LOAD_CONFLICT。 | | filePath | String | 音效文件路径。支持本地文件的 URI、本地文件的绝对路径或以 `/assets/` 开头的本地文件路径。
预加载的文件长度不得超过 20s。
不同平台支持的音效文件格式和 [start](#IAudioEffectPlayer-start) 一致。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 本方法只是预加载指定音效文件，只有调用 [start](#IAudioEffectPlayer-start) 方法才开始播放指定音效文件。 - 调用本方法预加载的指定音效文件可以通过 [unload](#IAudioEffectPlayer-unload) 卸载。 ### unload ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.unload(int effectId) ``` 卸载指定音效文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 仅在调用 [start](#IAudioEffectPlayer-start) 或 [preload](#IAudioEffectPlayer-preload) 后调用此接口。 ### unloadAll ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.unloadAll() ``` 卸载所有音效文件。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 ### pause ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.pause(int effectId) ``` 暂停播放音效文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [start](#IAudioEffectPlayer-start) 方法开始播放音效文件后，可以通过调用本方法暂停播放音效文件。 - 调用本方法暂停播放音效文件后，可调用 [resume](#IAudioEffectPlayer-resume) 方法恢复播放。 ### pauseAll ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.pauseAll() ``` 暂停播放所有音效文件。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [start](#IAudioEffectPlayer-start) 方法开始播放音效文件后，可以通过调用本方法暂停播放所有音效文件。 - 调用本方法暂停播放所有音效文件后，可调用 [resumeAll](#IAudioEffectPlayer-resumeall) 方法恢复所有播放。 ### resume ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.resume(int effectId) ``` 恢复播放音效文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 调用 [pause](#IAudioEffectPlayer-pause) 方法暂停播放音效文件后，可以通过调用本方法恢复播放。 ### resumeAll ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.resumeAll() ``` 恢复播放所有音效文件。 **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 调用 [pauseAll](#IAudioEffectPlayer-pauseall) 方法暂停所有正在播放音效文件后，可以通过调用本方法恢复播放。 ### setPosition ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.setPosition( int effectId, int position ) ``` 设置音效文件的起始播放位置。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID | | position | int | 音效文件起始播放位置，单位为毫秒。
你可以通过 [getDuration](#IAudioEffectPlayer-getduration) 获取音效文件总时长，position 的值应小于音效文件总时长。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** - 在播放在线文件时，调用此接口可能造成播放延迟的现象。 - 仅在调用 [start](#IAudioEffectPlayer-start) 后调用此接口。 ### getPosition ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.getPosition(int effectId) ``` 获取音效文件播放进度。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID | **返回值** - \>0：成功, 音效文件播放进度，单位为毫秒。 - < 0：失败 **注意** - 在播放在线文件时，调用此接口可能造成播放延迟的现象。 - 仅在调用 [start](#IAudioEffectPlayer-start) 后调用此接口。 ### setVolume ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.setVolume( int effectId, int volume ) ``` 调节指定音效的音量大小，包括音效文件和 PCM 音频。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID | | volume | int | 播放音量相对原音量的比值。单位为 \%。范围为 `[0, 400]`，建议范围是 `[0, 100]`。带溢出保护。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 仅在调用 [start](#IAudioEffectPlayer-start) 后调用此接口。 ### setVolumeAll ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.setVolumeAll(int volume) ``` 设置所有音效的音量大小，包括音效文件和 PCM 音效。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 播放音量相对原音量的比值。单位为 \%。范围为 `[0, 400]`，建议范围是 `[0, 100]`。带溢出保护。 | **返回值** - 0：调用成功。 - < 0：调用失败。查看 [ReturnStatus](70083#ReturnStatus) 获得更多错误说明。 **注意** 该接口的优先级低于 [setVolume](#IAudioEffectPlayer-setvolume)，即通过 [setVolume](#IAudioEffectPlayer-setvolume) 单独设置了音量的音效 ID，不受该接口设置的影响。 ### getVolume ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.getVolume(int effectId) ``` 获取当前音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID | **返回值** - \>0：成功, 当前音量值。 - < 0：失败 **注意** 仅在调用 [start](#IAudioEffectPlayer-start) 后调用此接口。 ### getDuration ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.getDuration(int effectId) ``` 获取音效文件时长。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effectId | int | 音效 ID | **返回值** - \>0：成功, 音效文件时长，单位为毫秒。 - < 0：失败 **注意** 仅在调用 [start](#IAudioEffectPlayer-start) 后调用此接口。 ### setEventHandler ```java public abstract int com.ss.bytertc.engine.audio.IAudioEffectPlayer.setEventHandler(IAudioEffectPlayerEventHandler handler) ``` 设置回调句柄。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | handler | IAudioEffectPlayerEventHandler | 参看 [IAudioEffectPlayerEventHandler](70081#IAudioEffectPlayerEventHandler)。 | **返回值** - 0：成功。 - < 0：失败。

实时音视频